Docker Swarm OpenTelemetry Collection Agent - Install

This guide explains how to install the Docker Swarm Collection Agent on a Docker Swarm with Foundry.

Prerequisites

• An active Docker Swarm. The agent runs one copy on every node of the Swarm, so every node needs Linux and Docker Engine 25.0 or newer.
• A shell on a manager node of the Swarm, where you run the commands in this guide. foundryctl cast deploys the agent with docker stack deploy, which runs only on a manager node.
• Ports 4317 and 4318 free on every node. To run the agent on a Swarm that runs self-hosted SigNoz, see Run on the same Swarm as self-hosted SigNoz.
• A SigNoz to send data to: SigNoz Cloud or a self-hosted SigNoz.

Install the Collection Agent

Step 1: Install foundryctl

Run this on a manager node:

curl -fsSL https://signoz.io/foundry.sh | bash

For manual install (Windows PowerShell, air-gapped, etc.) or PATH setup, see the foundry getting-started guide.

Step 2: Create casting.yaml

Create a file named casting.yaml on the manager node, with one document for the agent described in How it works:

apiVersion: v1alpha1
kind: CollectionAgent
metadata:
  name: signoz
spec:
  deployment:
    mode: docker
    flavor: swarm
  collector:
    spec:
      env:
        SIGNOZ_INGESTION_ENDPOINT: https://ingest.<region>.signoz.cloud:443
        SIGNOZ_INGESTION_KEY: <your-ingestion-key>
        OTEL_RESOURCE_ATTRIBUTES: deployment.environment=<your-environment>
      config:
        data:
          collector/agent/agent.yaml: |
            exporters:
              otlphttp/signoz:
                headers:
                  signoz-ingestion-key: ${env:SIGNOZ_INGESTION_KEY}

Verify these values:

• <region>: Your SigNoz Cloud region.
• <your-ingestion-key>: Your SigNoz Cloud ingestion key.
• <your-environment>: Your deployment environment, for example staging or production.

For every option of this casting, see the Docker Swarm example.

Step 3: Deploy

Run this from the directory that contains casting.yaml:

foundryctl cast -f casting.yaml

This command:

• writes the stack file compose.yaml to pours/collectionagent/ and the collector config agent.yaml to pours/collectionagent/collector/agent/;
• deploys compose.yaml with docker stack deploy, as the stack signoz;
• runs the agent as the service signoz_collector-agent, with one task on every node.

Run the same command again after editing casting.yaml. A changed collector config becomes a new Swarm config, and Swarm replaces the agent's tasks to use it.

foundryctl forge -f casting.yaml   # writes compose.yaml and agent.yaml under pours/collectionagent
docker stack deploy -c pours/collectionagent/compose.yaml signoz

Step 4: Verify the Collection Agent

Run this on the manager node to check that the agent started:

docker service logs signoz_collector-agent

The logs should include a line similar to the following from each node, where task IDs and node names vary:

signoz_collector-agent.0.qij0plduzksw@node-1    | ... Everything is ready. Begin running and processing data.

docker service ps signoz_collector-agent lists one Running task per node. In SigNoz, open Infrastructure Monitoring > Hosts: each node appears under its host name as data arrives. Check Logs Explorer to confirm container logs are flowing.

Customize the Collection Agent

Every change follows the same loop: edit casting.yaml, then run foundryctl cast -f casting.yaml again.

• Collector settings (image, environment): set them in the collector's spec (see spec fields). For example, to pin the collector image:

  Copy

  spec:
    collector:
      spec:
        image: otel/opentelemetry-collector-contrib:0.139.0

• Collector config (receivers, processors, pipelines): add it under spec.collector.spec.config.data, keyed collector/agent/agent.yaml. It merges into the generated config (see custom config files). For example, to collect host metrics every 30s:

  Copy

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

• Stack file (mounts, placement, memory limit): add patches under spec.patches against collectionagent/compose.yaml. For example, to mount the node's /var/log into the agent:

  Copy

  spec:
    patches:
      - target: collectionagent/compose.yaml
        operations:
          - op: add
            path: /services/collector-agent/volumes/-
            value:
              type: bind
              source: /var/log
              target: /var/log
              read_only: true

  Take the target and paths from the files under pours/. Each run regenerates them, so keep every change in casting.yaml.

foundryctl forge -f casting.yaml

Send data from your applications

Host metrics, container metrics, and container logs flow as soon as the agent is running. To send traces, metrics, and logs from your applications through the agent, see Send Data from Applications to the Collector.

Next Steps

• Configure the Docker Swarm Collection Agent
• Learn more about the Docker Swarm Collection Agent
• Telemetry Data Requirements for Infrastructure Monitoring
• Collector Configuration Best Practices