• Overview
• Set up Sumo logging driver plugin
  • Step 1 Configure Sumo to receive Docker logs
  • Step 2 Install Plugin
  • Step 3 Configure Docker to use the plugin
    • Option A Start a container to use Sumo driver
    • Option B Configure all containers on Docker host to use Sumo driver
  • Step 4 Search and analyze container log data
• log-opt options
• Uninstall the plugin

Overview

Docker logging driver plugins extend Docker's logging capabilities. You can use the Sumo logging driver plugin to send Docker container logs to the Sumo cloud-based service. Once your log data is in Sumo, you can use the Sumo web app to search and analyze your log data.

Note: Docker plugins are not yet supported on Windows; see Docker's logging driver plugin documentation.

The Sumo logging plugin driver is supported by Sumo Logic. If you have issues or questions, create an issue on GitHub.

Set up Sumo logging driver plugin

Setting up the Sumo plugin involves setting up an HTTP endpoint on Sumo to receive Docker container log data, and configuring Docker to use the plugin.

Step 1 Configure Sumo to receive Docker logs

In this step you create, on the Sumo service, an HTTP endpoint to receive your Docker logs. This process involves creating an HTTP source on a hosted collector in Sumo. In Sumo, collectors use sources to receive data.

1. If you don’t already have a Sumo account, you can create one by clicking the Free Trial button on https://www.sumologic.com/.

2. Create a hosted collector, following the instructions on Configure a Hosted Collector in Sumo help. (If you already have a Sumo hosted collector that you want to use, skip this step.)

3. Create an HTTP source on the collector you created in the previous step. For instructions, see HTTP Logs and Metrics Source in Sumo help.

4. When you have configured the HTTP source, Sumo will display the URL of the HTTP endpoint. Make a note of the URL. You will use it when you configure Docker to send data to Sumo.

Step 2 Install Plugin

On each Docker host with containers from which you want to collect container logs, install the plugin by running the following command in a terminal window:

$ docker plugin install sumologic/docker-logging-driver:1.0.6 --alias sumologic --grant-all-permissions

This defaults to amd64; for arm64, please pull the corresponding version:

$ docker plugin install sumologic/docker-logging-driver:1.0.6-aarch64 --alias sumologic --grant-all-permissions

NOTE The --alias is required for using it on AWS ECS

NOTE As of version 1.0.6, the plugin image is only available from the repo sumologic/docker-logging-driver. Prior to 1.0.6, the plugin was also available at store/sumologic/docker-logging-driver. However, with the deprecation of the Docker Publisher Center, the store repo has been deprecated as well.

To verify that the plugin is installed and enabled, run the following command:

$ docker plugin ls

ID                  NAME              DESCRIPTION                       ENABLED
b72ceb1530ff        sumologic         Sumo Logic logging driver         true

Step 3 Configure Docker to use the plugin

The Docker daemon on each Docker host has a default logging driver; each container on the Docker host uses the default driver, unless you configure it to use a different logging driver.

To use the Sumo plugin, you need to configure one or more containers to use the plugin. Use Option A below to use the sumologic plugin on a single container. Use Option B to set up all containers on a host to use the plugin.

Option A Start a container to use Sumo driver

To run a specific container with the logging driver:

• Use the --log-driver flag to specify the plugin.
• Use the --log-opt flag to specify the URL for the HTTP source you created in Step 1.

For example:

$ docker run --log-driver=sumologic --log-opt sumo-url=sumo_source_url

where sumo-source-url is the URL that Sumo assigned to the HTTP source you created.

The following command starts the container whose name is your_container to use the Sumo plugin, specifies the URL for the HTTP source, and sets several optional --log-opts options. For more information about these and other options, see log-opt options below.

$ docker run --log-driver=sumologic \
    --log-opt sumo-url=sumo-source-url \
    --log-opt sumo-batch-size=2000000 \
    --log-opt sumo-queue-size=400 \
    --log-opt sumo-sending-interval=2000ms \
    --log-opt sumo-compress=false \
    --log-opt ... \
    your_container

where:

• sumo_sourceurl is the URL of your HTTP Source.
• your_container identifies a container.

The container should start sending logs to Sumo Logic.

Option B Configure all containers on Docker host to use Sumo driver

The Docker daemon for a Docker host has a default logging driver, which each container on the host uses unless you configure it to use a different logging driver. This procedure shows you how to update a Docker host’s daemon.json file so that all of the containers on the host use the Sumo plugin, and know the URL for for sending logs to the Sumo service.

For more information about configuring Docker using daemon.json, see Daemon Configuration File in Docker help.

1. Find the Docker host’s daemon.json file, located by default in /etc/docker on Linux hosts.

2. To set the Sumo as the default logging driver for a Docker host, set the log-driver key to “sumologic”. For an example, see the daemon.json excerpt below this procedure.

3. To specify the URL for sending logs to Sumo, use the log-opts key to set sumo-url to the URL of the HTTP source you created in Step 1. For an example, see the daemon.json excerpt below this procedure.

4. Specify any other desired log options. For supported options, see log-opt options below.

5. Restart Docker for the changes to take effect.

Example excerpt from daemon.json

{
  "log-driver": "sumologic",
  "log-opts": {
    "sumo-url": "https://<deployment>.sumologic.com  		\
     /receiver/v1/http/<source_token>"
  }
}

Step 4 Search and analyze container log data

Once your container or containers are set up to send logs to Sumo, you can log onto the Sumo web app and start searching and analyzing the data. For help in getting started see Search in Sumo help.

log-opt options

To specify additional logging driver options, you can use the --log-opt NAME=VALUE flag.

Option	Required?	Default Value	Description
sumo-url	Yes		HTTP Source URL
sumo-source-category	No	HTTP source category	Source category to appear when searching in Sumo Logic by _sourceCategory. Use {{Tag}} as the placeholder for the tag option. If not specified, the source category of the HTTP source will be used.
sumo-source-name	No	container's name	Source name to appear when searching in Sumo Logic by _sourceName. Use {{Tag}}as the placeholder for the tag option. If not specified, it will be the container's name.
sumo-source-host	No	host name	Source host to appear when searching in Sumo Logic by _sourceHost. Use {{Tag}}as the placeholder for the tag option. If not specified, it will be the machine host name.
sumo-compress	No	true	Enable/disable gzip compression. Boolean.
sumo-compress-level	No	-1	Set the gzip compression level. Valid values are -1 (default), 0 (no compression), 1 (best speed) ... 9 (best compression).
sumo-batch-size	No	1000000	The number of bytes of logs the driver should wait for before sending them in bulk. If the number of bytes never reaches sumo-batch-size, the driver will send the logs in smaller batches at predefined intervals; see sumo-sending-interval.
sumo-sending-interval	No	2s	The maximum time the driver waits for number of logs to reach sumo-batch-size before sending the logs, even if the number of logs is less than the batch size. In the format 72h3m5s, valid time units are "ns", "us" (or "µs"), "ms", "s", "m", and "h".
sumo-proxy-url	No		Set a proxy URL.
sumo-insecure-skip-verify	No	false	Ignore server certificate validation. Boolean.
sumo-root-ca-path	No		Set the path to a custom root certificate.
sumo-server-name	No		Name used to validate the server certificate. By default, uses hostname of the sumo-url.
sumo-queue-size	No	100	The maximum number of log batches of size sumo-batch-size we can store in memory in the event of network failure, before we begin dropping batches. Thus in the worst case, the plugin will use sumo-batch-size * sumo-queue-size bytes of memory per container (default 100 MB).
tag	No	{{.ID}}	Specifies a tag for messages, which can be used in the "source category", "source name", and "source host" fields. Certain tokens of the form {{X}} are supported. Default value is {{.ID}}, the first 12 characters of the container ID. For more information and a list of supported tokens, see Log tags for logging driver in Docker help.

Uninstall the plugin

To cleanly disable and remove the plugin, run:

$ docker plugin disable sumologic/docker-logging-driver
$ docker plugin rm sumologic/docker-logging-driver

TLS 1.2 Requirement

Sumo Logic only accepts connections from clients using TLS version 1.2 or greater. To utilize the content of this repo, ensure that it's running in an execution environment that is configured to use TLS 1.2 or greater.