Connecting Docker to Honeycomb via Logspout

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. Grab the latest release with

docker pull honeycombio/logspout-honeycomb:1.6

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 \
  -h $HOST \
  -e "ROUTE_URIS=honeycomb://localhost" \
  -e "HONEYCOMB_WRITE_KEY=$(HONEYCOMB_WRITE_KEY)" \
  -e "HONEYCOMB_DATASET=$(HONEYCOMB_DATASET)" \
  --volume=/var/run/docker.sock:/var/run/docker.sock \
  --publish=127.0.0.1:8000:80 \
  logspout-honeycomb

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).

(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.

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.