Docker Swarm OpenTelemetry Collection Agent - Configure

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

Prerequisites

• Docker Swarm Collection Agent installed with Foundry (see the install guide)
• SigNoz Cloud account or self-hosted SigNoz instance
• A shell on a manager node of the Swarm
• 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

   A changed collector config becomes a new Swarm config, and Swarm replaces the agent's tasks to use it.

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

   Copy

   docker service logs --since 5m signoz_collector-agent

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 that runs as a Swarm service, attach the agent to the application's overlay network as Attach the agent to an overlay network shows, then add this to the application's service in its stack file:

services:
  <your-app>:
    environment:
      OTEL_EXPORTER_OTLP_ENDPOINT: http://signoz_collector-agent:4318
      OTEL_SERVICE_NAME: <service-name>

Verify these values:

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

The agent's service name balances requests across its tasks on all nodes. For an application on a node outside a container, use http://localhost:4318, and from outside the Swarm, a node's address: every node publishes the agent's ports in host mode. 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/*
                        - /run/credentials/*
                        - /run/k3s/containerd/*
                        - /var/lib/docker/*
                        - /var/lib/containers/storage/*
                        - /var/lib/kubelet/*
                        - /snap/*
                        - ^/mnt/backup$

Lists replace, so restate Foundry's ten 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 mappings of the Swarm stack, service, task, and node labels 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 stack 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 nodes 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

Every agent task runs the scrape, so SigNoz receives a target's metrics from each node. The agent reaches a target by its service name on an overlay network they share, as Attach the agent to an overlay network shows.

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: [my-app: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/deploy/resources
          value:
            limits:
              memory: 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 Swarm as self-hosted SigNoz

Self-hosted SigNoz publishes ports 4317 and 4318 through the Swarm routing mesh on every node, so the agent publishes 14317 and 14318 instead and sends to SigNoz's ingester over the signoz-network overlay network.

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

metadata:
  name: signoz-agent
spec:
  collector:
    spec:
      env:
        SIGNOZ_INGESTION_ENDPOINT: http://signoz-ingester:4318
  patches:
    - target: collectionagent/compose.yaml
      operations:
        - op: replace
          path: /services/collector-agent/ports/0/published
          value: 14317
        - op: replace
          path: /services/collector-agent/ports/1/published
          value: 14318
        - op: add
          path: /services/collector-agent/networks
          value: [signoz-network]
        - op: add
          path: /networks
          value:
            signoz-network:
              external: true

The agent then runs as signoz-agent_collector-agent in its own stack signoz-agent, the name commands and application endpoints use from then on, and applications on a node send to localhost:14318.

Attach the agent to an overlay network

To attach the agent to an overlay network, add this patch to casting.yaml:

spec:
  patches:
    - target: collectionagent/compose.yaml
      operations:
        - op: add
          path: /services/collector-agent/networks
          value: [<your-overlay-network>]
        - op: add
          path: /networks
          value:
            <your-overlay-network>:
              external: true

Verify these values:

• <your-overlay-network>: The overlay network your application's services use, as docker network ls shows it.

Migrate to Foundry

If you run the agent as the signoz-collection-agent service 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 every node runs Docker Engine 25.0 or newer, then install foundryctl and create casting.yaml as the install guide shows. On a Swarm that runs self-hosted SigNoz, also add the change in Run on the same Swarm 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 ports the Foundry agent publishes on every node, remove the old agent's service and leave the rest of the stack signoz, such as self-hosted SigNoz, running. Run this on a manager node:

   Copy

   docker service rm signoz_signoz-collection-agent

   If docker service ls lists the old agent as signoz-collection-agent, remove that service instead.

4. To deploy 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 Swarm Collection Agent Overview
• Telemetry Data Requirements for Infrastructure Monitoring
• Collector Configuration Best Practices