OpenTelemetry Collector for Docker - Install

Prerequisites

Before installing the OpenTelemetry Collector, ensure you have:

Docker Engine 20.10+ installed and running
Administrative access to the Docker host

Installation

Step 1: Create Configuration Directory

Creates a dedicated directory to organize the OpenTelemetry Collector configuration file.

mkdir -p ~/opentelemetry-collector
cd ~/opentelemetry-collector

Step 2: Create Collector Configuration

Defines how the OpenTelemetry Collector receives, processes, and exports telemetry data to SigNoz.

Create otel-config.yaml:

otel-config.yaml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
  hostmetrics:
    collection_interval: 60s
    scrapers:
      cpu: {}
      disk: {}
      load: {}
      filesystem: {}
      memory: {}
      network: {}
      paging: {}
      process:
        mute_process_name_error: true
        mute_process_exe_error: true
        mute_process_io_error: true
      processes: {}

processors:
  batch:
    send_batch_size: 1000
    timeout: 10s
  # Ref: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/resourcedetectionprocessor/README.md
  resourcedetection:
    detectors: [env, system] # Before system detector, include ec2 for AWS, gcp for GCP and azure for Azure.
    # Using OTEL_RESOURCE_ATTRIBUTES envvar, env detector adds custom labels.
    timeout: 2s
    system:
      hostname_sources: [os] # alternatively, use [dns,os] for setting FQDN as host.name and os as fallback

extensions:
  health_check: {}
  zpages: {}

exporters:
  otlp:
    endpoint: "ingest.<YOUR_REGION>.signoz.cloud:443"
    tls:
      insecure: false
    headers:
      "signoz-ingestion-key": "<YOUR_INGESTION_KEY>"
  debug:
    verbosity: normal

service:
  telemetry:
    metrics:
      level: basic
  extensions: [health_check, zpages]
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]
    metrics/internal:
      receivers: [hostmetrics]
      processors: [resourcedetection, batch]
      exporters: [otlp]
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]

Configuration Steps:

Set the <region> to match your SigNoz Cloud region
Replace <your-ingestion-key> with your SigNoz ingestion key

Step 3: Run the OpenTelemetry Collector

Starts the OpenTelemetry Collector as a Docker container to begin receiving and forwarding telemetry data to SigNoz.

docker run --name opentelemetry-collector \
  --restart unless-stopped \
  --detach \
  -p 4317:4317 -p 4318:4318 \
  -v "$(pwd)/otel-config.yaml":/etc/otelcol-contrib/config.yaml \
  otel/opentelemetry-collector-contrib:0.130.1

Verification

Check Collector Status

Verifies that the OpenTelemetry Collector container is running and operational.

Check if container is running

docker ps | grep opentelemetry-collector

Check collector logs

docker logs opentelemetry-collector

You will see the OpenTelemetry Collector logs indicating successful startup and readiness to process data.

Troubleshooting

Container Name Already in Use

If you get an error about the container name already being in use:

# Check existing containers
docker ps -a | grep opentelemetry-collector

# Stop and remove the existing container
docker stop opentelemetry-collector
docker rm opentelemetry-collector

# Then re-run the installation command