Log routing for Docker container logs
Go Makefile Shell
Latest commit 6c88eec Dec 31, 2016 @mattaitchison mattaitchison committed on GitHub first pass at tests (#218)
* added FakeRoundTripper and container rename test
* tests: run in circleci, added TestRoutingFrom
Failed to load latest commit information.
adapters retry tcp errors and don't hang forever on failure Jan 18, 2016
custom install ca-certificates fixes #247 Dec 30, 2016
debug primarily designed new boot output, but came with it architectural ch… Mar 30, 2015
httpstream Removed deprecated library hosted in google code in favor of its new … Jan 19, 2016
router first pass at tests (#218) Dec 31, 2016
routesapi Filter by label (#236) Dec 15, 2016
transports Add TLS transport. Fixes #116. Sep 2, 2015
.dockerignore better versioning Feb 13, 2015
.gitignore better versioning Feb 13, 2015
CHANGELOG.md fixed version and date... May 23, 2016
Dockerfile Updating Dockerfile base image to gliderlabs/alpine:3.4 from 3.3 (#242) Dec 15, 2016
Dockerfile.custom Some help for working on custom modules. Jun 1, 2016
Dockerfile.dev install ca-certificates fixes #247 Dec 30, 2016
LICENSE -added versioning Feb 12, 2015
MODULES.md Add a note about build.sh needing to be in the docker build directory Aug 29, 2016
Makefile first pass at tests (#218) Dec 31, 2016
README.md Update README.md Dec 29, 2016
SPONSORS -added versioning Feb 12, 2015
VERSION bump May 23, 2016
build-custom.sh Some help for working on custom modules. Jun 1, 2016
build.sh install ca-certificates fixes #247 Dec 30, 2016
circle.yml first pass at tests (#218) Dec 31, 2016
logspout.go Filter by label (#236) Dec 15, 2016
modules.go Add TLS transport. Fixes #116. Sep 2, 2015
run-custom.sh Some help for working on custom modules. Jun 1, 2016



CircleCI Docker pulls IRC Channel

Docker Hub automated builds for gliderlabs/logspout:latest and progrium/logspout:latest are now pointing to the release branch. For master, use gliderlabs/logspout:master. Individual versions are also available as saved images in releases.

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. It also has an extensible module system.

It's a mostly stateless log appliance. It's not meant for managing log files or looking at history. It is just a means to get your logs out to live somewhere else, where they belong.

For now it only captures stdout and stderr, but a module to collect container syslog is planned.

Getting logspout

Logspout is a very small Docker container (15.2MB virtual, based on Alpine). Pull the latest release from the index:

$ docker pull gliderlabs/logspout:latest

You can also download and load a specific version:

$ curl -s dl.gliderlabs.com/logspout/v2.tgz | docker load

Using logspout

Route all container output to remote syslog

The simplest way to use logspout is to just take all logs and ship to a remote syslog. Just pass a syslog URI (or several comma separated URIs) as the command. Here we show use of the tls encrypted transport option in the URI. Also, we always mount the Docker Unix socket with -v to /var/run/docker.sock:

$ docker run --name="logspout" \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    gliderlabs/logspout \

logspout will gather logs from other containers that are started without the -t option and are configured with a logging driver that works with docker logs (journald and json-file).

To see what data is used for syslog messages, see the syslog adapter docs.

Ignoring specific containers

You can tell logspout to ignore specific containers by setting an environment variable when starting your container, like so:-

$ docker run -d -e 'LOGSPOUT=ignore' image

Or, by adding a label which you define by setting an environment variable when running logspout:

$ docker run --name="logspout" \
    -e EXCLUDE_LABEL=logspout.exclude \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
$ docker run -d --label logspout.exclude=true image

Including specific containers

You can tell logspout to only include certain containers by setting filter parameters on the URI:

$ docker run \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    gliderlabs/logspout \

$ docker run \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    gliderlabs/logspout \

$ docker run \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    gliderlabs/logspout \

# Forward logs from containers with both label 'a' starting with 'x', and label 'b' ending in 'y'.
$ docker run \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    gliderlabs/logspout \

Note that you must URL-encode parameter values such as the comma in filter.sources and filter.labels.

Multiple logging destinations

You can route to multiple destinations by comma-separating the URIs:

$ docker run \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    gliderlabs/logspout \

Inspect log streams using curl

Using the httpstream module, you can connect with curl to see your local aggregated logs in realtime. You can do this without setting up a route URI.

$ docker run -d --name="logspout" \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    --publish= \
$ curl

You should see a nicely colored stream of all your container logs. You can filter by container name and more. You can also get JSON objects, or you can upgrade to WebSocket and get JSON logs in your browser.

See httpstream module for all options.

Create custom routes via HTTP

Using the routesapi module logspout can also expose a /routes resource to create and manage routes.

$ curl $(docker port `docker ps -lq` 8000)/routes \
    -X POST \
    -d '{"source": {"filter": "db", "types": ["stderr"]}, "target": {"type": "syslog", "addr": "logs.papertrailapp.com:55555"}}'

That example creates a new syslog route to Papertrail of only stderr for containers with db in their name.

Routes are stored on disk, so by default routes are ephemeral. You can mount a volume to /mnt/routes to persist them.

See routesapi module for all options.

Detecting timeouts in Docker log streams

Logspout relies on the Docker API to retrieve container logs. A failure in the API may cause a log stream to hang. Logspout can detect and restart inactive Docker log streams. Use the environment variable INACTIVITY_TIMEOUT to enable this feature. E.g.: INACTIVITY_TIMEOUT=1m for a 1-minute threshold.


The standard distribution of logspout comes with all modules defined in this repository. You can remove or add new modules with custom builds of logspout. Just edit the modules.go file and do a docker build.

Builtin modules

  • adapters/raw
  • adapters/syslog
  • transports/tcp
  • transports/tls
  • transports/udp
  • httpstream
  • routesapi

Third-party modules

Loggly support

Use logspout to stream your docker logs to Loggly via the Loggly syslog endpoint.

$ docker run --name logspout -d --volume=/var/run/docker.sock:/var/run/docker.sock \
    -e SYSLOG_STRUCTURED_DATA="<Loggly API Key>@41058 tag=\"some tag name\"" \
    gliderlabs/logspout \


As usual, pull requests are welcome. You can also propose releases by opening a PR against the release branch from master. Please be sure to bump the version and update CHANGELOG.md and include your changelog text in the PR body.

Discuss logspout development with us on Freenode in #gliderlabs.


This project was made possible by DigitalOcean and Deis.