Docker OpenTelemetry Collection Agent - Install

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

Prerequisites

• A Linux host with Docker Engine 25.0 or newer.
• The Docker Compose plugin (docker compose) on the same host.
• Ports 4317, 4318, 8888, and 13133 free on the host. To run the agent on the host that runs self-hosted SigNoz, see Run on the same host 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 the Docker host:

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 Docker host, with one document for the agent described in How it works:

apiVersion: v1alpha1
kind: CollectionAgent
metadata:
  name: signoz
spec:
  deployment:
    mode: docker
    flavor: compose
  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 Compose example.

Step 3: Deploy

Run this from the directory that contains casting.yaml:

foundryctl cast -f casting.yaml

This command:

• writes the Compose file compose.yaml to pours/collectionagent/ and the collector config agent.yaml to pours/collectionagent/collector/agent/;
• applies compose.yaml with docker compose up -d, as the Compose project signoz;
• runs the agent in the container signoz-collector-agent-1.

Run the same command again after editing casting.yaml, then run docker restart signoz-collector-agent-1 so the agent reads the new config.

foundryctl forge -f casting.yaml   # writes compose.yaml and agent.yaml under pours/collectionagent
docker compose -f pours/collectionagent/compose.yaml up -d

Step 4: Verify the Collection Agent

Run this on the Docker host to check that the agent started:

docker logs signoz-collector-agent-1

The logs should include a line similar to the following:

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

In SigNoz, open Infrastructure Monitoring > Hosts: your host 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, run foundryctl cast -f casting.yaml again, then run docker restart signoz-collector-agent-1.

• 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

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

  Copy

  spec:
    patches:
      - target: collectionagent/compose.yaml
        operations:
          - op: add
            path: /services/collector-agent/volumes/-
            value: /var/log:/var/log:ro

  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 Collection Agent
• Learn more about the Docker Collection Agent
• Telemetry Data Requirements for Infrastructure Monitoring
• Collector Configuration Best Practices