Install Scalyr Agent (Docker)

These instructions are for installing the Scalyr Agent in a Docker container. If you plan to run the Agent directly on Linux, see the Linux installation page. For Windows, see the Windows installation page.

The Scalyr Agent is a daemon that uploads logs and system metrics to the Scalyr servers. This page provides streamlined instructions to get you up and running quickly in a Docker environment.

In our recommended architecture, you run the Scalyr Agent in its own Docker container on each host running Docker in your system. Docker provides a logging framework by which Standard Output and Standard Error from all containers on the same host are gathered. The Scalyr Agent watches these logs and uploads them to the Scalyr backend, along with metrics.

We support two Docker logging framework drivers: json-file and syslog. We recommend the json-file logging driver, but this document describes both methods.

Docker JSON

Instructions to install the Scalyr Agent using the Docker JSON File Logging Driver.

1. Download the official Scalyr Agent Docker image from Docker Hub

docker pull scalyr/scalyr-agent-docker-json

The default :latest tag points to the latest released agent version.

2. Configure the Scalyr API key and Scalyr upload server by setting the `SCALYR_API_KEY` environment variable:

-e SCALYR_API_KEY=<Your API key>

Or by modular agent.d snippet. In this example, we will create /tmp/api_key.json:

(log in to see your API token)

3. Launch the scalyr-agent container, specifying the SCALYR_API_KEY environment variable. Be sure to substitute /var/run/docker.sock with the path to your Docker socket and /var/lib/docker/containers with the path to the Docker containers directory:

docker run -d --name scalyr-docker-agent \
-e SCALYR_API_KEY=<Your API key> \
-v /var/run/docker.sock:/var/scalyr/docker.sock \
-v /var/lib/docker/containers:/var/lib/docker/containers \
scalyr/scalyr-agent-docker-json

Or by modular agent.d snippet:

docker run -d --name scalyr-docker-agent \
-v /tmp/api_key.json:/etc/scalyr-agent-2/agent.d/api_key.json \
-v /var/run/docker.sock:/var/scalyr/docker.sock \
-v /var/lib/docker/containers:/var/lib/docker/containers \
scalyr/scalyr-agent-docker-json

4. Start your other containers. Below is a simple "Hello, World" example.

docker run -d ubuntu /bin/sh -c 'while true; do echo Hello, World!; sleep 1; done'

Docker Syslog

Listed below are instructions to install the Scalyr Agent using the Syslog Logging Driver.

To start the Scalyr Agent container, please do the following:

1. Download the official Scalyr Agent Docker image from Docker Hub

docker pull scalyr/scalyr-agent-docker-syslog

2. Configure the Scalyr API key and Scalyr upload server following the same instructions above for Docker JSON.

3. Launch the scalyr-agent container, specifying the SCALYR_API_KEY environment variable. Be sure to substitute /var/run/docker.sock with the path to your Docker socket:

docker run -d --name scalyr-docker-agent \
-e SCALYR_API_KEY=<Your API key> \
-v /var/run/docker.sock:/var/scalyr/docker.sock \
-p 601:601 \
scalyr/scalyr-agent-docker-syslog

Or by modular agent.d snippet:

docker run -d --name scalyr-docker-agent \
-v /tmp/api_key.json:/etc/scalyr-agent-2/agent.d/api_key.json \
-v /var/run/docker.sock:/var/scalyr/docker.sock \
-p 601:601 \
scalyr/scalyr-agent-docker-syslog

4. Configure other containers to send their logs to Scalyr via the Scalyr Agent container. When you start a container, you must supply these additional options to direct their logs to the Scalyr Agent container: --log-driver=syslog --log-opt syslog-address=tcp://127.0.0.1:601.

For example, to start a container running a "Hello World" example, you would execute:

docker run \
--log-driver=syslog \
--log-opt syslog-address=tcp://127.0.0.1:601  \
-d ubuntu /bin/sh -c 'while true; do echo Hello, World!; sleep 1; done'

Troubleshooting tips

You may need to determine the path for the Docker API socket and the containers directory on your machine.

These instructions assumes typical locations for the socket located at /var/run/docker.sock and the containers directory at /var/lib/docker/containers.

For the Docker socket:

  • Another typical location for the socket is at /run/docker.sock.
  • Be sure that you find the path to the true socket and not just a symlink to it. Use ls -l to verify.
  • If both /run/docker.sock and /var/run/docker.sock are not symlinks, use /var/run/docker.sock.
  • If neither file exists, try executing netstat --unix -l | grep docker.sock to locate the socket.
  • Make sure your user has permission to access docker.sock.

Finally, if you wish to have separate stdout and stderr streams, do not allocate the pseudo-TTY for your container with docker run -t; doing so causes the docker daemon to redirect stderr to stdout.

Conclusion and Next Steps

If you've had any trouble, please let us know. If this is your first time using Scalyr, this would be an excellent time to head on to the Getting Started guide.

Now that you have the Scalyr Docker Agent up and running, please see Configuring Scalyr Agent (Docker) for more configuration instructions such as: