Connecting Logspout to Honeycomb

For processing structured data from Docker containers, we recommend using logspout, described as:

Logspout is a log router for Docker containers that runs inside Docker. It attaches to all containers on a host, then routes their logs wherever you want.

Our Honeycomb adapter follows the same philosophy, allowing you to configure the adapter with your team/dataset identifiers and stream data over to Honeycomb for analysis.

Data expectations 🔗

Logspout is ultimately just a mechanism for getting logs out of your containerized environment

We still expect the events themselves to be structured JSON. If the log lines aren’t structured JSON, the message will be captured under a "message" key alongside Logspout metadata like stream name, docker image, container name, container ID, etc.

Pairing the Honeycomb logspout adapter with our various other connectors (e.g. nginx, MongoDB) is still in the works! Please let us know if that’s what you’re waiting on.

Transmitting events to Honeycomb 🔗

We provide a Honeycomb adapter for logspout. This will pull a Docker image of logspout with the Honeycomb adapter baked in, so that logs captured by logspout will be routed to Honeycomb’s ingest API.

The Honeycomb adapter can be configured in two ways—environment variables or via the logspout routesapi module. Running logspout with environment variables looks like the following:

docker run \
  -d \
  -h $HOST \
  -e "ROUTE_URIS=honeycomb://localhost" \
  -e "HONEYCOMB_WRITE_KEY=YOUR_API_KEY" \
  -e "HONEYCOMB_DATASET=logspout" \
  --volume=/var/run/docker.sock:/var/run/docker.sock \
  --publish=127.0.0.1:8000:80 \
  honeycombio/logspout-honeycomb:1.13

Note: logspout only gathers logs from containers started without the -t option (we don’t want a pseudo-TTY) and are configured with a logging driver that works with docker logs (journald and json-file).

Note: logspout will only gather logs from containers when it receives a “create” event for that container. Therefore, it will not fill logs from containers that are already running when it is started. You may need to re-deploy the task / service / container to cause a container create event that logstash will pick up on in order to forward its logs.

(An example routesapi invocation can be found on logspout-honeycomb’s README.)

The sample rate for the dataset is also configurable via the HONEYCOMB_SAMPLE_RATE environment variable. For example, -e "HONEYCOMB_SAMPLE_RATE=10" will send Honeycomb 1 out of every 10 events and drop the rest. To read more about sampling, check out our Sampling Guide.

Example extracted Logspout fields 🔗

If the log lines being fed into Logspout look like the following:

{"foo":"bar","baz":42.1}

… the Honeycomb events produced will look something like (with Logspout metadata appended to the main payload):

field name	type	value
foo	string	bar
baz	float	42.1
stream	string	stdout
logspout_container	string	/myapp
logspout_container_id	string	abfb910784a412077e4cb43731354d2be2cc4ea7210be63e3f53c1f47d10084f
logspout_hostname	string	abfb910784a4
logspout_docker_image	string	logspout-honeycomb
router_hostname	string	myhost

If they, instead, happen to just be text:

the quick fox jumped over the lazy dog

… then the Honeycomb event will simply capture the plaintext output under a "message" key alongside the other Logspout metadata fields. We strongly recommend using a structured logging approach to maximize the value of Honeycomb (and to make your life easier in the long run!).

Advanced options 🔗

Instructions for other functionality, like excluding or including specific containers, can be found in logspout documentation.

Open source 🔗

logspout-honeycomb is open source, Apache 2.0 licensed. Its source is on GitHub.