Docker Collection Agent - Install

This guide walks you through installing the OpenTelemetry Collector contrib image on your Docker host. The collector is configured to collect host metrics, container metrics, container logs, and forward application traces to SigNoz.

Prerequisites

Docker Engine 20.10+ installed and running
SigNoz Cloud account or self-hosted SigNoz instance
Ports 4317, 4318 available on the host

Step 1: Create Collector Configuration

Create a config.yaml file with the following content. This config is tailored for SigNoz usage: it collects host metrics, container metrics, container logs, and accepts OTLP data from instrumented applications.

config.yaml

receivers:
  # OTLP: accept traces, metrics, and logs from instrumented apps (SDKs, agents)
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
  # Host metrics: CPU, disk, memory, network, etc. (root_path for container)
  hostmetrics:
    collection_interval: 60s
    root_path: /hostfs
    scrapers:
      cpu: {}
      disk: {}
      load: {}
      filesystem: {}
      memory: {}
      network: {}
      paging: {}
      process:
        mute_process_name_error: true
        mute_process_exe_error: true
        mute_process_io_error: true
        mute_process_user_error: true
      processes: {}
  # Container metrics from Docker daemon
  docker_stats:
    endpoint: unix:///var/run/docker.sock
    collection_interval: 10s
    timeout: 20s
  # Container logs: Docker JSON log files
  filelog:
    include: [/var/lib/docker/containers/*/*-json.log]
    start_at: end  # Only new logs collected from this point. Use "beginning" to also collect existing logs.
    include_file_name: false
    include_file_path: true
    operators:
      - id: container-parser
        type: container
        format: docker
        add_metadata_from_filepath: false

processors:
  batch:
    send_batch_size: 1000
    timeout: 10s
  resourcedetection:
    detectors: [env, system, docker]
    timeout: 2s
    system:
      hostname_sources: [os]
  memory_limiter:
    check_interval: 5s
    limit_mib: 4000
    spike_limit_mib: 800

exporters:
  otlp:
    endpoint: 'ingest.<region>.signoz.cloud:443'
    tls:
      insecure: false
    headers:
      'signoz-ingestion-key': '<your-ingestion-key>'

extensions:
  health_check:
    endpoint: 0.0.0.0:13133
  pprof:
    endpoint: 0.0.0.0:1777
  zpages:
    endpoint: 0.0.0.0:55679

service:
  extensions: [health_check, pprof, zpages]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, resourcedetection, batch]
      exporters: [otlp]
    metrics:
      receivers: [otlp, hostmetrics, docker_stats]
      processors: [memory_limiter, resourcedetection, batch]
      exporters: [otlp]
    logs:
      receivers: [otlp, filelog]
      processors: [memory_limiter, resourcedetection, batch]
      exporters: [otlp]

Verify the following values:

<region>: Your SigNoz Cloud region
<your-ingestion-key>: Your SigNoz Cloud ingestion key

Step 2: Run the Collector

Create a docker-compose.yaml file:

docker-compose.yaml

services:
  signoz-collection-agent:
    image: otel/opentelemetry-collector-contrib:0.139.0
    container_name: signoz-collection-agent
    restart: unless-stopped
    user: "0:0"
    network_mode: host
    environment:
      - OTEL_RESOURCE_ATTRIBUTES=deployment.environment=<your-environment>
    volumes:
      - ./config.yaml:/etc/otelcol-contrib/config.yaml
      - /var/lib/docker/containers:/var/lib/docker/containers:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /:/hostfs:ro

Start the collector:

docker compose up -d

docker run --name signoz-collection-agent \
  --restart unless-stopped \
  --detach \
  --user 0:0 \
  --network host \
  -e OTEL_RESOURCE_ATTRIBUTES="deployment.environment=<your-environment>" \
  -v "$(pwd)/config.yaml":/etc/otelcol-contrib/config.yaml \
  -v /var/lib/docker/containers:/var/lib/docker/containers:ro \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v /:/hostfs:ro \
  otel/opentelemetry-collector-contrib:0.139.0

Verify the following values:

<your-environment>: The environment name for the deployment

Step 3: Validate

Check that the collector is running:

docker logs signoz-collection-agent

You should see log lines indicating the receivers started successfully:

... Everything is ready. Begin running and processing data.

In SigNoz, navigate to Infrastructure Monitoring → Hosts and verify your host appears. Check Logs Explorer to confirm container logs are flowing.

Troubleshooting

Container Name Already in Use

docker stop signoz-collection-agent
docker rm signoz-collection-agent

Then re-run the installation command from Step 2.

Permission Denied on Docker Socket

If the collector logs show permission errors accessing /var/run/docker.sock, ensure the container runs with appropriate permissions. The docker run and compose examples above use user: "0:0" which runs as root. Alternatively, add the Docker group:

docker run --group-add $(getent group docker | cut -d: -f3) ...

No Host Metrics Appearing

Verify the host filesystem is mounted correctly:

docker inspect signoz-collection-agent | grep -A5 hostfs

Ensure the root_path: /hostfs setting in the hostmetrics receiver matches the mount target.

docker_stats Receiver Fails to Start

If collector logs show:

Error response from daemon: client version 1.25 is too old. Minimum supported API version is 1.44

Your Docker daemon requires a newer API version than the receiver's default. Add api_version to the docker_stats receiver in config.yaml, matching the minimum version reported in the error:

receivers:
  docker_stats:
    endpoint: unix:///var/run/docker.sock
    api_version: "1.44"

Configuration Errors

Check the collector logs for configuration parsing errors:

docker logs signoz-collection-agent 2>&1 | head -50

Common causes:

Invalid YAML syntax in config.yaml
Missing or incorrect SigNoz ingestion key
Port conflicts with other services on 4317 or 4318