Install Docker OpenTelemetry integration

Monitor your Docker containers by installing an OpenTelemetry Collector directly on Linux hosts. This guide provides complete setup instructions for collecting container metrics and optional log collection using either the New Relic NRDOT Collector (recommended) or OpenTelemetry Collector Contrib.

Before you begin

A New Relic account with a
Docker Engine (API version 1.25+) installed and running
Access to the Docker socket (typically /var/run/docker.sock)
One of the following collectors installed on a Linux host:
- NRDOT Collector (recommended - New Relic's OpenTelemetry distribution), or
- OpenTelemetry Collector Contrib (alternative option)
Network access from the Linux host to:
- Docker Engine socket
- One of the New Relic OTLP endpoints
For log collection: Read permissions to /var/lib/docker/containers/ directory (typically requires root or docker group membership)

Verify your setup

bash

$docker version --format '{{.Client.APIVersion}}'

Expected output: 1.25 or higher

Integration steps

Follow these steps to configure Docker container monitoring with OpenTelemetry. Choose your collector type below:

Install NRDOT Collector

The NRDOT Collector is New Relic's distribution of OpenTelemetry with pre-configured settings optimized for New Relic.

Sugerencia

If you already have NRDOT Collector installed, you can skip to Step 2 to configure it for Docker monitoring.

DEB Installation (Debian/Ubuntu):

bash

$# Example version - check releases for latest: https://github.com/newrelic/nrdot-collector-releases/releases
$export collector_version="1.10.0"
$export collector_arch="amd64"  # or arm64
$
$curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${collector_version}/nrdot-collector_${collector_version}_linux_${collector_arch}.deb" -o collector.deb
$sudo dpkg -i collector.deb
$
$# Disable auto-start until configuration is complete
$sudo systemctl disable nrdot-collector
$sudo systemctl stop nrdot-collector

RPM Installation (RHEL/CentOS/Fedora):

bash

$# Example version - check releases for latest: https://github.com/newrelic/nrdot-collector-releases/releases
$export collector_version="1.10.0"
$export collector_arch="x86_64"  # or arm64
$
$curl -L "https://github.com/newrelic/nrdot-collector-releases/releases/download/${collector_version}/nrdot-collector_${collector_version}_linux_${collector_arch}.rpm" -o collector.rpm
$sudo rpm -i collector.rpm
$
$# Disable auto-start until configuration is complete
$sudo systemctl disable nrdot-collector
$sudo systemctl stop nrdot-collector

Other Linux distributions: For archive installations or other methods, see the NRDOT installation guide.

Verify installation:

bash

$nrdot-collector --version

Expected output: Version information

Configure the collector for Docker monitoring

For NRDOT Collector, create a standalone Docker monitoring configuration file that replaces the default configuration.

Importante

Standalone vs. Combined monitoring: This configuration monitors Docker containers only. If you also need host metrics (CPU, memory, disk) or system logs, use the NRDOT Collector's default configuration which includes the hostmetrics and filelog receivers, and add the docker_stats receiver to it.

Create /etc/nrdot-collector/docker-stats-config.yaml with the following content:

receivers:
  # Docker Stats Receiver - collects container metrics
  docker_stats:
    endpoint: unix:///var/run/docker.sock
    collection_interval: 15s
    timeout: 5s
    api_version: "1.25"
    # Most metrics required for New Relic UI are enabled by default:
    # CPU: container.cpu.usage.total, container.cpu.utilization
    # Memory: container.memory.usage.total, container.memory.percent
    # Network: container.network.io.usage.tx_bytes, container.network.io.usage.rx_bytes
    #          container.network.io.usage.tx_dropped, container.network.io.usage.rx_dropped
    # Storage: container.blockio.io_service_bytes_recursive
    #
    # The following metrics need to be explicitly enabled:
    metrics:
      # Required for New Relic UI
      container.pids.count:
        enabled: true
      # Additional network error metrics
      container.network.io.usage.tx_errors:
        enabled: true
      container.network.io.usage.rx_errors:
        enabled: true

processors:
  # Batch processor optimizes data transmission
  batch:
    timeout: 10s
    send_batch_size: 1024

  # Transform processor - removes descriptions and units
  transform:
    metric_statements:
      - context: metric
        statements:
          - set(description, "")
          - set(unit, "")
exporters:
  otlp_http:
    endpoint: ${env:OTEL_EXPORTER_OTLP_ENDPOINT:-https://otlp.nr-data.net}
    headers:
      api-key: ${env:NEW_RELIC_LICENSE_KEY}
    compression: gzip

service:
  pipelines:
    metrics/docker:
      receivers: [docker_stats]
      processors: [transform, batch]
      exporters: [otlp_http]

Configure Docker socket permissions

The collector needs access to the Docker socket to collect container metrics. Grant the collector user access to the Docker group.

bash

$# Add nrdot-collector user to docker group
$sudo usermod -aG docker nrdot-collector
$
$# Verify the user was added
$groups nrdot-collector
$
$# Restart Docker to apply group changes
$sudo systemctl restart docker
$
$# Test Docker socket access
$sudo -u nrdot-collector docker ps

If the test command succeeds and shows your containers, permissions are correctly configured.

Optional - Configure log collection

You can also collect logs from your Docker containers using the OpenTelemetry receiver creator with the Docker observer extension.

Importante

Requirements for log collection:

The collector process must have read permissions to the /var/lib/docker/containers/ directory. This typically requires running the collector as root or adding the collector user to the docker group.
Container ports must be exposed for the receiver creator to discover and scrape logs from containers.

Add the log collection configuration to your existing docker-stats-config.yaml.

extensions:
  # Docker observer - discovers running containers
  docker_observer:
    endpoint: unix:///var/run/docker.sock
    use_hostname_if_present: true

receivers:
  # Your existing dockerstats receiver...

  # Receiver creator - dynamically creates filelog receivers for discovered containers
  receiver_creator:
    watch_observers: [docker_observer]
    receivers:
      filelog:
        rule: type == "container"
        config:
          include:
            - /var/lib/docker/containers/`container_id`/`container_id`-json.log
          poll_interval: 200ms
          start_at: end
          include_file_name: false
          include_file_path: false
          operators:
            - id: container-parser
              type: container
              format: docker
              add_metadata_from_filepath: false

processors:
  # Your existing processors...

  # Add entity type attribute for logs (required for New Relic entity correlation)
  attributes/logs:
    actions:
      - key: nr.entity_type
        value: CONTAINER
        action: upsert

service:
  extensions: [docker_observer]
  pipelines:
  # Your existing metrics pipeline...

    logs:
      receivers: [receiver_creator]
      processors: [attributes/logs, batch]
      exporters: [otlp_http]

Configure authentication and start the collector

Configure authentication by adding your New Relic and OTLP endpoint to the collector service.

NRDOT Collector environment variables:

Variable	Description	Default	Required
`NEW_RELIC_LICENSE_KEY`	Your New Relic ingest license key	None	Yes
`OTEL_EXPORTER_OTLP_ENDPOINT`	New Relic OTLP endpoint for your region	`https://otlp.nr-data.net` (US)	No

Endpoint configuration:

US region: https://otlp.nr-data.net (default)
EU region: https://otlp.eu01.nr-data.net

For more endpoint options, see the New Relic OTLP documentation.

Configure the systemd service:

Now you'll configure the NRDOT Collector service to use your Docker monitoring configuration and authentication credentials. This involves creating a systemd override to specify the custom config file and environment variables.

Create a systemd override directory:

bash

$sudo mkdir -p /etc/systemd/system/nrdot-collector.service.d

Create an override configuration to use the Docker stats config. Replace YOUR_LICENSE_KEY with your New Relic license key and YOUR_OTLP_ENDPOINT with the appropriate endpoint for your region:

bash

$cat <<EOF | sudo tee /etc/systemd/system/nrdot-collector.service.d/override.conf
$[Service]
$Environment="NEW_RELIC_LICENSE_KEY=YOUR_LICENSE_KEY"
$Environment="OTEL_EXPORTER_OTLP_ENDPOINT=YOUR_OTLP_ENDPOINT"
$ExecStart=
$ExecStart=/usr/bin/nrdot-collector --config=/etc/nrdot-collector/docker-stats-config.yaml
$EOF

Reload systemd, enable and start the collector:

bash

$sudo systemctl daemon-reload
$sudo systemctl enable nrdot-collector
$sudo systemctl start nrdot-collector
$
$# Verify the collector is running
$sudo systemctl status nrdot-collector
$
$# Check logs for any errors
$journalctl -u nrdot-collector -f

Sugerencia

The empty ExecStart= line clears the default command before setting the new one. This ensures the collector uses only the Docker stats configuration instead of the default configuration.

Install OpenTelemetry Collector Contrib

Download and install the OpenTelemetry Collector Contrib following the official installation guide.

Sugerencia

If you already have OpenTelemetry Collector Contrib installed, you can skip to Step 2 to configure it for Docker monitoring.

Verify installation:

bash

$otelcol-contrib --version

Expected output: Version information (minimum v0.88.0 recommended)

Configure the collector for Docker monitoring

For OpenTelemetry Collector Contrib, merge the receivers, processors, exporters, and service pipelines into your configuration file (typically /etc/otelcol-contrib/config.yaml).

receivers:
  # Docker Stats Receiver - collects container metrics
  docker_stats:
    endpoint: unix:///var/run/docker.sock
    collection_interval: 15s
    timeout: 5s
    api_version: "1.25"
    # Most metrics required for New Relic UI are enabled by default:
    # CPU: container.cpu.usage.total, container.cpu.utilization
    # Memory: container.memory.usage.total, container.memory.percent
    # Network: container.network.io.usage.tx_bytes, container.network.io.usage.rx_bytes
    #          container.network.io.usage.tx_dropped, container.network.io.usage.rx_dropped
    # Storage: container.blockio.io_service_bytes_recursive
    #
    # The following metrics need to be explicitly enabled:
    metrics:
      # Required for New Relic UI
      container.pids.count:
        enabled: true
      # Additional network error metrics
      container.network.io.usage.tx_errors:
        enabled: true
      container.network.io.usage.rx_errors:
        enabled: true

processors:
  # Resource detection - adds host metadata
  resourcedetection:
    detectors: [system, docker]
    system:
      resource_attributes:
        host.name:
          enabled: true
        host.id:
          enabled: true
  # Batch processor - optimizes data transmission
  batch:
    timeout: 30s
    send_batch_size: 512
  # Transform processor - removes descriptions and units
  transform:
    metric_statements:
      - context: metric
        statements:
          - set(description, "")
          - set(unit, "")
expor
exporters:
  # New Relic OTLP Exporter
  otlp_http/newrelic:
    endpoint: ${env:NEWRELIC_OTLP_ENDPOINT}
    headers:
      api-key: ${env:NEWRELIC_LICENSE_KEY}
    compression: gzip
    timeout: 30s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s

service:
  pipelines:
    metrics:
      receivers: [docker_stats]
      processors: [resourcedetection, transform, batch]
      exporters: [otlp_http/newrelic]

Save the file and ensure the otelcol-contrib system user can read it.

Configure Docker socket permissions

The collector needs access to the Docker socket to collect container metrics. Grant the collector user access to the Docker group.

bash

$# Add otelcol-contrib user to docker group
$sudo usermod -aG docker otelcol-contrib
$
$# Verify the user was added
$groups otelcol-contrib
$
$# Restart Docker to apply group changes
$sudo systemctl restart docker
$
$# Test Docker socket access
$sudo -u otelcol-contrib docker ps

If the test command succeeds and shows your containers, permissions are correctly configured.

Optional - Configure log collection

You can also collect logs from your Docker containers using the OpenTelemetry receiver creator with the Docker observer extension.

Importante

Requirements for log collection:

The collector process must have read permissions to the /var/lib/docker/containers/ directory. This typically requires running the collector as root or adding the collector user to the docker group.
Container ports must be exposed for the receiver creator to discover and scrape logs from containers.

Merge the following configuration with your existing config file at /etc/otelcol-contrib/config.yaml.

extensions:
  # Docker observer - discovers running containers
  docker_observer:
    endpoint: unix:///var/run/docker.sock
    use_hostname_if_present: true

receivers:
  # Your existing dockerstats receiver...

  # Receiver creator - dynamically creates filelog receivers for discovered containers
  receiver_creator:
    watch_observers: [docker_observer]
    receivers:
      filelog:
        rule: type == "container"
        config:
          include:
            - /var/lib/docker/containers/`container_id`/`container_id`-json.log
          poll_interval: 200ms
          start_at: end
          include_file_name: false
          include_file_path: false
          operators:
            - id: container-parser
              type: container
              format: docker
              add_metadata_from_filepath: false

processors:
  # Your existing processors...

  # Add entity type attribute for logs (required for New Relic entity correlation)
  attributes/logs:
    actions:
      - key: nr.entity_type
        value: CONTAINER
        action: upsert

service:
  extensions: [docker_observer]
  pipelines:
  # Your existing metrics pipeline...

    logs:
      receivers: [receiver_creator]
      processors: [attributes/logs]
      exporters: [otlp_http/newrelic]

Configure authentication and start the collector

Configure authentication by adding your New Relic and OTLP endpoint to the collector service.

OpenTelemetry Collector Contrib environment variables:

Variable	Description	Required
`NEWRELIC_LICENSE_KEY`	Your New Relic ingest license key	Yes
`NEWRELIC_OTLP_ENDPOINT`	New Relic OTLP endpoint for your region	Yes

Endpoint configuration:

US region: https://otlp.nr-data.net:4318
EU region: https://otlp.eu01.nr-data.net:4318

For more endpoint options, see the New Relic OTLP documentation.

Configure the systemd service:

Now you'll configure the OpenTelemetry Collector Contrib service with your authentication credentials. This involves setting environment variables for your New Relic license key and OTLP endpoint.

Create a systemd override directory:

bash

$sudo mkdir -p /etc/systemd/system/otelcol-contrib.service.d

Create environment.conf with your configuration. Replace YOUR_LICENSE_KEY with your New Relic license key and YOUR_OTLP_ENDPOINT with the appropriate endpoint for your region:

bash

$cat <<EOF | sudo tee /etc/systemd/system/otelcol-contrib.service.d/environment.conf
$[Service]
$Environment="NEWRELIC_LICENSE_KEY=YOUR_LICENSE_KEY"
$Environment="NEWRELIC_OTLP_ENDPOINT=YOUR_OTLP_ENDPOINT"
$EOF

Reload systemd and restart the collector:

bash

$sudo systemctl daemon-reload
$sudo systemctl restart otelcol-contrib
$
$# Verify the collector is running
$sudo systemctl status otelcol-contrib
$
$# Check logs for any errors
$journalctl -u otelcol-contrib -f

View your data in New Relic

Once the integration is complete and the collector is running, you should start seeing data in New Relic within a few minutes:

Go to one.newrelic.com > All capabilities > All entities.
Search for your Docker host by hostname or container name.
Click your entity to view Docker container metrics and details.
Explore the Summary page to see performance metrics, resource usage, and container health.

The Docker container metrics are attached to the Metric event type. You can query this data for troubleshooting purposes or to create custom charts and dashboards.

Troubleshooting

If you encounter issues during setup, see the Docker monitoring troubleshooting guide for detailed diagnostic steps and solutions for common problems including:

Collector startup and configuration issues
Missing metrics or data connectivity problems
Permission denied errors
Performance optimization
Log collection troubleshooting

Next steps

Now that you have Docker container monitoring set up, you can enhance your observability stack:

Create custom dashboards: Build custom dashboards using NRQL to analyze container performance patterns
Set up alerts: Create proactive monitoring with alert conditions for critical container metrics
Explore metrics: Review the complete Docker metrics reference for detailed metric descriptions and alerting recommendations
OpenTelemetry fundamentals: Deepen your understanding with OpenTelemetry in New Relic
Explore additional Docker OpenTelemetry configuration examples in the New Relic OpenTelemetry examples repository

Install Docker OpenTelemetry integration

Before you begin

Verify your setup

Check Docker version and API

Test Docker socket access

Test network connectivity

Integration steps

Install NRDOT Collector

Sugerencia

Configure the collector for Docker monitoring

Importante

Configure Docker socket permissions

Optional - Configure log collection

Importante

Configure authentication and start the collector

Sugerencia

Install OpenTelemetry Collector Contrib

Sugerencia

Configure the collector for Docker monitoring

Configure Docker socket permissions

Optional - Configure log collection

Importante

Configure authentication and start the collector

View your data in New Relic

Troubleshooting

Next steps

Install Docker OpenTelemetry integration

Before you begin .css-21sua1{background:none;border:none;width:0;padding:0;}

Verify your setup

Test Docker socket access

Test network connectivity

Integration steps

Install NRDOT Collector

Sugerencia

Configure the collector for Docker monitoring

Importante

Configure Docker socket permissions

Optional - Configure log collection

Importante

Configure authentication and start the collector

Sugerencia

Install OpenTelemetry Collector Contrib

Sugerencia

Configure the collector for Docker monitoring

Configure Docker socket permissions

Optional - Configure log collection

Importante

Configure authentication and start the collector

View your data in New Relic

Troubleshooting

Next steps

Before you begin