Sumo Logic is a nifty service that makes it easy watch and analyze your apps’ logs. You install a collector local to the app in question, point it at some files to watch, and your logs are sent to the cloud, where they can be sliced and diced from a nice web UI.
At a high level, Sumo Logic wants to transform big data logs into operational information. But at a practical level, it’s nice not to have to SSH to a production machine and tail or grep enormous files to take your app’s pulse. Not to mention the idea is totally in line with one of the Twelve Factors: treating logs as event streams enables better understanding of an app’s behavior over time.
I’ve had success using SumoLogic at OpenX, so I wanted to give their free trial a shot for a personal project. The only limitations are a 500MB of data per day limit and 7 days of retention. I was surprised not to find anything on the web for installing Sumo Logic alongside a Dockerized app, and I had a couple of Docker-based candidates. So without further ado, here’s how to add Sumo Logic to a Dockerized app:
1. Sign up for Sumo Logic Free
Head over to sumologic.com/signup to sign up. The only catch here is that you’ll need a company email address. For the project I’m going to use SumoLogic for, I own and manage my own domain, so it wasn’t too much trouble to create an email address using my registrar’s mail service. Since I host the domain separately, I did have to add an MX record to my zone file to point to the registrar’s mail server. For example, with DigitalOcean.
2. Download a Collector
Once you confirm your email address and log in, you be stepped through a process for downloading and installing a collector. I chose the Installed Collector and downloaded sumocollector_19.91-2_amd64.deb, becuase my Docker image is based on Ubuntu.
After downloading the collector, the setup wizard proceeds to a screen that spins until it detects a newly installed collector. I didn’t yet know how I was going to install it, and I got logged out of Sumo Logic anyway due to inactivity, so I abandoned the wizard at that point. The Sumo Logic UI changed itself as soon as it detected that my first collector had been installed.
- As I plan to install the Sumo Logic collector during the
docker buildprocess, I uploaded the.debfile to a Dropbox and grabbed the public link to use later.
3. Create Access Keys
When a collector client is installed it has to have some way of authenticating to the Sumo Logic server. The docs for creating a sumo.conf file (we’ll get there soon) offer two choices: (1) provide your Sumo Logic email and password, or (2) provide access keys generated from the UI. The latter is recommended if only to avoid storing a username/password in plaintext. Keys can be generated from Manage → Collectors → Access Keys → Create.
4. Augment your Docker Container
Here’s the Docker-specific part of installing Sumo Logic. We’ll add some lines to our app’s Dockerfile and author two files that are ADDed to the container during a docker build. I assume working knowledge of Docker, but here is the list of Dockerfile commands for good measure.
4.1 Create sumo.conf
First create a sumo.conf file like the following:
name={collector_name}
accessid={your_access_id}
accesskey={your_access_key}
where name is an arbitrary name for this collector, and accessid and accesskey are those generated in step 3. There are many more conf options specified here but the important ones, namely sources, can actually be configured through the UI later on.
By convention I put Docker-specific files into .docker/{resource}, so this one goes to .docker/sumo/sumo.conf. It’ll be referenced in our Dockerfile shortly.
4.2 Modify your Dockerfile
Add a block like the following to your Dockerfile (assumed to live in the root of your app’s code), preferably before your actual app is added:
# install sumologic
RUN apt-get -qq update
RUN apt-get install -y wget
RUN wget https://www.dropbox.com/path/to/sumocollector_19.91-2_amd64.deb
RUN dpkg -i sumocollector_19.91-2_amd64.deb
RUN rm sumocollector_19.91-2_amd64.deb
ADD .docker/sumo/sumo.conf /etc/sumo.conf
ADD .docker/sumo/start_sumo /etc/my_init.d/start_sumo
Let’s break this down:
RUN apt-get -qq update
Update sources. This may not be necessary, but I like to put this before each dependancy installed by my Dockerfile to avoid issues with image caching.
RUN apt-get install -y wget
RUN wget https://www.dropbox.com/path/to/sumocollector_19.91-2_amd64.deb
We’ll use wget to grab the collector file we uploaded in step 2. You may opt to ADD the file locally, but this option avoids having to check the resource into your app’s source code, while housing it in a consistent location. Better practice would be to store it in some kind of artifact repository and version it.
RUN dpkg -i sumocollector_19.91-2_amd64.deb
RUN rm sumocollector_19.91-2_amd64.deb
Install the debian package and clean up.
ADD .docker/sumo/sumo.conf /etc/sumo.conf
Copy the newly created sumo.conf file to the place where the collector expects to find it.
Before we get to the last line, let’s pause. If you were able to catch the output from installing the collector, you saw something like:
Preparing to unpack sumocollector_19.91-2_amd64.deb ...
Unpacking sumocollector (1:19.91-2) ...
Setting up sumocollector (1:19.91-2) ...
configuring collector....
configuring collector to run as root
Detected Ubuntu:
Installing the SumoLogic Collector daemon using init.d..
Adding system startup for /etc/init.d/collector ...
/etc/rc0.d/K20collector -> ../init.d/collector
/etc/rc1.d/K20collector -> ../init.d/collector
/etc/rc6.d/K20collector -> ../init.d/collector
/etc/rc2.d/S20collector -> ../init.d/collector
/etc/rc3.d/S20collector -> ../init.d/collector
/etc/rc4.d/S20collector -> ../init.d/collector
/etc/rc5.d/S20collector -> ../init.d/collector
Collector has been successfully installed. Please provide account credential in /etc/sumo.conf and start it up via service or init.d script!
It was only after sifting through my docker output that I saw this and learned about the existence of a sumo.conf file. Before that, nothing was happening in the Sumo Logic UI because no collector had been correctly installed and started, even when I started the container. Anyway, we got /etc/sumo.conf out of the way, so what about starting it up “via service or init.d script”?
My solution was to include a simple bash script that starts the collector service on startup. But my Dockerfile extends phusion/baseimage-docker, which uses a custom init system. So the last Dockerfile command,
ADD .docker/sumo/start_sumo /etc/my_init.d/start_sumo
adds a file called start_sumo like:
#!/bin/bash
service collector start
into /etc/my_init.d. Make sure it’s executable with chmod +x. Like the conf file, this is saved into .docker/sumo/start_sumo of the app code repository.
I am very open to more elegant ways for getting the Sumo Logic collector to start. I’d also like to see how non-baseimage users deal with init requirements. I would have done this as a runit script as recommended by the baseimage-docker README, but the collector script appears to automatically daemonize itself, which breaks runit.
5. Build and Deploy!
I ran docker build and docker run as usual, and voilà!, the newly installed collector popped up in Manage → Collectors.
6. Configure Sources
Before we start seeing logs, we have to tell Sumo what a log file is. I clicked Manage → Collectors → Add → Add Source and added a Local File entry that had the absolute path to a log file I was interested in. One of the Sumo Logic videos I watched noted that specifying /path/to/log/dir/** will pick up all log files in a directory.
I waited a couple of minutes, and log messages started coming into the UI. Sweet! Keep in mind that multiple sources can be added for a single collector.
So far, I’ve learned that I can get a bird’s eye view of all my logs from Manage → Status, and look at actual log messages from Search. I haven’t spent time really getting to know the various queries yet, but if they’re worth writing about, expect another post.
Possible Improvement: The above example installs Sumo Logic inside the app container. An alternate approach might have Sumo installed on the host (or in its own Docker container), reading log files from a shared data volume. This has the benefits of (1) requiring only a single Sumo Logic install for potentially more than one app container, and (2) architectural separation of app from log consumption.
That’s it! This turned out to be surprisingly simple. Kudos to Sumo Logic for offering an easy to use service + free tier that’s totally feasible for smallish apps.
This is a guest post from Caleb Sotelo who is a software engineer at OpenX and has been reprinted with his permission. You can view the original here.
