Docker Source Template

The Docker source template creates an OpenTelemetry configuration that can be pushed to a remotely managed OpenTelemetry collector (abbreviated as otelcol). By creating this source template and pushing the config to the appropriate OpenTelemetry agent, you can collect Docker logs and metrics to Sumo Logic.

Fields created by the source template

When you create a source template, the following fields are automatically added (if they don’t already exist):

• sumo.datasource. Fixed value of docker.
• deployment.environment. This is a user-configured field set at the time of collector installation. It identifies the environment where the docker env resides, such as dev, prod, or qa.

Prerequisites

This section provides instructions for configuring metrics and log collection for the Sumo Logic Docker app.

For metrics collection

Metrics are collected through the Docker Stats Receiver of OpenTelemetry. This requires Docker API version 1.22+ and only Linux is supported.

After installing Sumo OpenTelemetry collector to docker host machine, you need to make sure that otelcol-sumo user (created during Sumo OpenTelemetry collector installation) has permission to access docker.sock before pushing Docker ST to the collector. The command for this may vary depending on the linux OS which is being used. Here are commands which can help do that:

• You can grant read and write access to the user otelcol-sumo for the docker.sock file using the command:

  sudo setfacl -m user:otelcol-sumo:rw /var/run/docker.sock
• If docker.sock has docker group as the owner you can add otelcol-sumo user to this docker group using command:

  sudo usermod -aG docker otelcol-sumo

For logs collection

To collect Docker container event logs, execute the following command on the host machine and keep it running to monitor all Docker container-related events. The command requires a JSON file path where these container events will be stored.

docker events -f 'type=container' --format '{{json .}}' > <PATH_TO_JSON> & disown

The path to this JSON file will be required in the next step, where events are sent to Sumo Logic through a filelog receiver and seen as part of the Docker - Overview dashboard. Also, you can add additional parameters to this command to send events for specific containers. Learn more.

Ensure that the otelcol has adequate permissions to access all log file paths. Execute the following command for the same:

sudo setfacl -R -m d:u:otelcol-sumo:r-x,u:otelcol-sumo:r-x,g:otelcol-sumo:r-x <PATH_TO_LOG_FILE>

Configuring the Docker source template

Follow these steps to set up and deploy the source template to a remotely managed OpenTelemetry collector.

Step 1: Set up remotely managed OpenTelemetry collector

In this step, we'll install the collector and add a uniquely identifiable tag to these collectors.

1. Classic UI. In the main Sumo Logic menu, select Manage Data > Collection > OpenTelemetry Collection.
   New UI. In the Sumo Logic top menu select Configuration, and then under Data Collection select OpenTelemetry Collection. You can also click the Go To... menu at the top of the screen and select OpenTelemetry Collection.
2. On the OpenTelemetry Collection page, click + Add Collector.
3. In the Set up Collector step:
   1. Choose your platform (for example, Linux).
   2. Enter your Installation Token.
   3. Under Tag data on Collector level, add a new tag to identify these collectors as having Apache running on them (for example, application = Apache).
   4. Leave the Collector Settings at their default values to configure collectors as remotely managed.
   5. Under Generate and run the command to install the collector, copy and run the installation command in your system terminal where the collector needs to be installed.
4. After installation is complete, click Next to proceed.
5. Select a source template (for example, Apache source template) to start collecting logs from all linked collectors, then proceed with the data configuration.
   

To revisit this screen later: From the Classic UI, select Manage Data > Collection > Source Template. From the New UI, select Configuration > Source Template.

Step 2: Configure the source template

In this step, you will configure the yaml required for Docker Collection. Below are the inputs required for configuration:

• Name. Name of the source template.
• Description. Description for the source template.
• Docker Event log location. Enter the path of the JSON file generated through the command in the prerequisite section.
• Endpoint. Address to reach the desired Docker daemon (default: unix:///var/run/docker.sock).
• Excluded Image List. A list of strings, regexes, or globs whose referent container image names will not be among the queried containers for scrapping metrics. Learn more about excluded_images.
• Fields/Metadata. You can provide any customer fields to be tagged with the data collected. By default, Sumo Logic tags _sourceCategory with the value otel/docker.

Advance options for log collection can be used as follows:

• Timestamp Format. By default, Sumo Logic will automatically detect the timestamp format of your logs. However, you can manually specify a timestamp format for a source by configuring the following:
  • Timestamp locator. Use a Go regular expression to match the timestamp in your logs. Ensure the regular expression includes a named capture group called timestamp_field.
  • Layout. Specify the exact layout of the timestamp to be parsed. For example, - %Y-%m-%dT%H:%M:%S.%LZ. To learn more about the formatting rules, refer to this guide.
  • Location (Time zone). Define the geographic location (timezone) to use when parsing a timestamp that does not include a timezone. The available locations depend on the local IANA Time Zone database. For example, America/New_York. See more examples here.

Processing Rules. You can add processing rules for logs/metrics collected. To learn more, refer to Processing Rules.

Step 3: Push the source template to the desired remotely managed collectors

info

A new source template will always be created with the latest version of the source template.

Follow the below steps to create a data collection configuration to gather the required logs and link them to all the collectors with the help of collector tags.

1. Complete the source template form with the name and file path for your logs (for example, error logs or access logs), then click Next.
2. Under Link Collectors, you will have the option to link the collectors using the collector name or by adding tags to find the group of collectors (for example, application = Apache).
   
3. Preview and confirm the collectors that will be linked (fetched automatically) to the newly created source template.
   
   
4. Click Next to complete the source template creation. In the background, the system will apply the configuration to all the linked collectors and will start collecting the respective telemetry data from the remote host (in the example, it would start collecting Apache error logs).
5. Click the Log Search or Metrics Search icons to search for and analyze your data collected for this source template.

info

Refer to the changelog for information on periodic updates to this source template.