Docker OpenTelemetry Collection Agent - Configure

The install guide provides a working config: one agent container on each Docker host collects host metrics, container metrics, container logs, and data from instrumented applications. This page shows how to customize it in casting.yaml.

Prerequisites

• Docker Collection Agent installed with Foundry (see the install guide)
• SigNoz Cloud account or self-hosted SigNoz instance
• A shell on the Docker host
• The casting.yaml and foundryctl you installed with

Apply Changes

For each change:

1. Add the section's snippet to casting.yaml. Foundry already generates the default receivers and processors, so add only what you change.

2. Run this from the directory that contains casting.yaml to apply the change:

   Copy

   foundryctl cast -f casting.yaml
   docker restart signoz-collector-agent-1

   Foundry updates the agent's config, and the agent restarts with it.

3. View the agent's logs to confirm there are no configuration errors:

   Copy

   docker logs --since 5m signoz-collector-agent-1

4. In SigNoz, confirm data in Infrastructure Monitoring for host metrics, the Docker container metrics dashboard for container metrics, Logs for container logs, and Traces for application traces.

Send Data from Applications to the Collector

Host metrics, container metrics, and container logs flow as soon as the agent is running.

Where and how to send data from your application

To send traces, metrics, and logs from an application, instrument it with OpenTelemetry (language guides), then point it at the agent. For an application in a container, add this to its service in its Compose file:

services:
  <your-app>:
    environment:
      OTEL_EXPORTER_OTLP_ENDPOINT: http://host.docker.internal:4318
      OTEL_SERVICE_NAME: <service-name>
    extra_hosts:
      - "host.docker.internal:host-gateway"

Verify these values:

• <your-app>: Your application's service in its Compose file.
• <service-name>: The name your application shows under in SigNoz.

The host-gateway entry points host.docker.internal at the Docker host, where the agent listens. For an application on the host itself, use http://localhost:4318, and from another host, the Docker host's address. For OTLP over gRPC, set OTEL_EXPORTER_OTLP_PROTOCOL=grpc and port 4317.

Redeploy the application and send it some traffic. Within a minute it shows under Services in SigNoz.

Collect Host Metrics

To collect host metrics every 30s, add this to casting.yaml:

spec:
  collector:
    spec:
      config:
        data:
          collector/agent/agent.yaml: |
            receivers:
              hostmetrics:
                collection_interval: 30s

To stop a scraper, set it to null under scrapers, for example paging: null.

Exclude filesystem mounts

To stop reporting the filesystem mounted at /mnt/backup, add this to casting.yaml:

spec:
  collector:
    spec:
      config:
        data:
          collector/agent/agent.yaml: |
            receivers:
              hostmetrics:
                scrapers:
                  filesystem:
                    exclude_mount_points:
                      mount_points:
                        - /dev/*
                        - /proc/*
                        - /sys/*
                        - /run/credentials/*
                        - /run/k3s/containerd/*
                        - /var/lib/docker/*
                        - /var/lib/containers/storage/*
                        - /var/lib/kubelet/*
                        - /snap/*
                        - ^/mnt/backup$

Lists replace, so restate Foundry's nine default entries, the ones above ^/mnt/backup$.

Collect Container Metrics

For the metrics and a dashboard, see Docker Container Metrics.

To collect container metrics every 30s, add this to casting.yaml:

spec:
  collector:
    spec:
      config:
        data:
          collector/agent/agent.yaml: |
            receivers:
              docker_stats:
                collection_interval: 30s

Foundry collects container metrics every 60s by default.

Map container labels to resource attributes

To add the com.example.team container label to container metrics as team, add this to casting.yaml:

spec:
  collector:
    spec:
      config:
        data:
          collector/agent/agent.yaml: |
            receivers:
              docker_stats:
                container_labels_to_metric_labels:
                  com.example.team: team

The map merges, so Foundry's default com.docker.compose.project and com.docker.compose.service mappings stay.

Exclude containers from metrics

To stop collecting metrics for containers by image, add this to casting.yaml:

spec:
  collector:
    spec:
      config:
        data:
          collector/agent/agent.yaml: |
            receivers:
              docker_stats:
                excluded_images:
                  - 'otel/opentelemetry-collector-contrib*'
                  - /.*pause.*/

Entries match the image name exactly, as a glob, or as a regular expression between slashes.

Collect Container Logs

For Docker daemon logs and other log sources, see Collecting Docker Logs.

To keep a container's logs out of the agent's collection, add this to its service in its Compose file and redeploy it:

services:
  <your-app>:
    logging:
      driver: local

Verify these values:

• <your-app>: The service whose logs you keep out.

The agent collects the logs of containers that use the json-file log driver, Docker's default.

Disable Logs Collection

To stop collecting container logs, add this to casting.yaml:

spec:
  collector:
    spec:
      config:
        data:
          collector/agent/agent.yaml: |
            receivers:
              filelog: null
            service:
              pipelines:
                logs:
                  receivers: [otlp/http, otlp/grpc]

Lists replace, so the logs pipeline is restated with Foundry's two OTLP receivers.

Resource Detection

To detect only host and Docker attributes on a host outside AWS, GCP, and Azure, add this to casting.yaml:

spec:
  collector:
    spec:
      config:
        data:
          collector/agent/agent.yaml: |
            processors:
              resourcedetection:
                detectors: [env, system, docker]

Lists replace, so detectors holds only the detectors you list.

Custom resource attributes

To add team=backend to all telemetry, add this to casting.yaml:

spec:
  collector:
    spec:
      env:
        OTEL_RESOURCE_ATTRIBUTES: deployment.environment=<your-environment>,team=backend

Verify these values:

• <your-environment>: Your deployment environment, for example staging or production.

Scrape Prometheus Metrics from Containers

To scrape a Prometheus endpoint every 60s, add this to casting.yaml:

spec:
  collector:
    spec:
      config:
        data:
          collector/agent/agent.yaml: |
            receivers:
              prometheus:
                config:
                  scrape_configs:
                    - job_name: my-app
                      scrape_interval: 60s
                      static_configs:
                        - targets: [localhost:9090]
            service:
              pipelines:
                metrics:
                  receivers: [otlp/http, otlp/grpc, docker_stats, hostmetrics, prometheus]

Lists replace, so the metrics pipeline is restated with Foundry's default receivers.

Tune Batch and Memory Limiter

For sizing guidance, see Collector Configuration Best Practices.

To send larger batches, add this to casting.yaml:

spec:
  collector:
    spec:
      config:
        data:
          collector/agent/agent.yaml: |
            processors:
              batch:
                send_batch_size: 2000
                send_batch_max_size: 4000

Foundry's defaults are send_batch_size: 1000, send_batch_max_size: 2048, and timeout: 10s.

Container Memory Limit

To cap the agent's memory at 1 GiB, add this patch to casting.yaml:

spec:
  patches:
    - target: collectionagent/compose.yaml
      operations:
        - op: add
          path: /services/collector-agent/mem_limit
          value: 1g

Foundry's memory_limiter processor uses a fixed limit_mib: 4000. Size it to the memory limit with percentages, in the same document:

spec:
  collector:
    spec:
      config:
        data:
          collector/agent/agent.yaml: |
            processors:
              memory_limiter:
                limit_mib: null
                spike_limit_mib: null
                limit_percentage: 80
                spike_limit_percentage: 25

Add Custom Processors to Pipelines

To add a processor to the traces pipeline, add this to casting.yaml:

spec:
  collector:
    spec:
      config:
        data:
          collector/agent/agent.yaml: |
            processors:
              attributes/team:
                actions:
                  - key: team
                    value: platform
                    action: insert
            service:
              pipelines:
                traces:
                  processors: [memory_limiter, resourcedetection, attributes/team, batch]

Lists replace, so restate Foundry's processors memory_limiter, resourcedetection, and batch, with yours before batch.

Common Deployment Scenarios

Run on the same host as self-hosted SigNoz

To run the agent on the host that runs self-hosted SigNoz, add this to casting.yaml:

metadata:
  name: signoz-agent
spec:
  collector:
    spec:
      env:
        SIGNOZ_INGESTION_ENDPOINT: http://localhost:4318
      config:
        data:
          collector/agent/agent.yaml: |
            receivers:
              otlp/grpc:
                protocols:
                  grpc:
                    endpoint: 0.0.0.0:14317
              otlp/http:
                protocols:
                  http:
                    endpoint: 0.0.0.0:14318

If the agent already runs as signoz-collector-agent-1, remove it with docker rm -f signoz-collector-agent-1 before you apply this. The agent then runs as signoz-agent-collector-agent-1 in its own Compose project, the name commands use from then on, and applications on the host send to localhost:14318.

Use bridge networking

To run the agent on a bridge network, add this patch to casting.yaml:

spec:
  patches:
    - target: collectionagent/compose.yaml
      operations:
        - op: remove
          path: /services/collector-agent/network_mode
        - op: add
          path: /services/collector-agent/hostname
          value: <host-name>
        - op: add
          path: /services/collector-agent/ports
          value: ["4317:4317", "4318:4318"]
        - op: add
          path: /services/collector-agent/networks
          value: [monitoring]
        - op: add
          path: /networks
          value:
            monitoring:
              driver: bridge

Verify these values:

• <host-name>: The Docker host's name.

On a bridge network, host network metrics report the agent container's network interfaces.

Migrate to Foundry

If you run the agent as the signoz-collection-agent container with your own config.yaml, move it to Foundry so that casting.yaml holds its whole setup and every change follows Apply Changes.

1. To describe the agent in Foundry, check that the host runs Docker Engine 25.0 or newer, then install foundryctl and create casting.yaml as the install guide shows. On a host that runs self-hosted SigNoz, also add the change in Run on the same host as self-hosted SigNoz.

2. To keep your config.yaml customizations, add them to casting.yaml under spec.collector.spec.config.data, keyed collector/agent/agent.yaml, and your environment variables under spec.collector.spec.env. For example, for container metrics every 10s and a team resource attribute:

   Copy

   spec:
     collector:
       spec:
         env:
           OTEL_RESOURCE_ATTRIBUTES: deployment.environment=<your-environment>,team=backend
         config:
           data:
             collector/agent/agent.yaml: |
               receivers:
                 docker_stats:
                   collection_interval: 10s

   Verify these values:

   • <your-environment>: Your deployment environment, for example staging or production.

   Foundry merges them over its own config: maps merge and lists replace, so restate whole lists, with Foundry's names otlp/http and otlp/grpc for your otlp receiver and otlphttp/signoz for your otlphttp exporter.

3. To free the host ports the Foundry agent binds, remove the old agent's container. Run this on the Docker host:

   Copy

   docker rm -f signoz-collection-agent

4. To start the agent with Foundry, run this from the directory that contains casting.yaml:

   Copy

   foundryctl cast -f casting.yaml

   Then verify the Collection Agent as Step 4 of the install guide shows.

Next Steps

• Docker Collection Agent Overview
• Telemetry Data Requirements for Infrastructure Monitoring
• Collector Configuration Best Practices