This guide explains how to install the VM Collection Agent on a virtual machine or server: with Foundry on Linux, and from the OpenTelemetry Collector's release packages on macOS and Windows.
Prerequisites
- One of these hosts:
- A Linux host with systemd 238 or newer, with
sudo,curl, andtaron it. - A Mac (Apple silicon or Intel) with macOS 12 or newer.
- A Windows 10 version 1803, Windows Server 2019, or newer host (x64), with administrator access for the MSI. The MSI starts its default config first, which also needs TCP ports
1777,9411,14250,14268, and55679and UDP ports6831and6832free.
- A Linux host with systemd 238 or newer, with
- Ports
4317,4318,8888, and13133free 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 on Linux with Foundry
Step 1: Install foundryctl
Run this on the Linux host:
curl -fsSL https://signoz.io/foundry.sh | bashFor a manual install or PATH setup, see the foundry getting-started guide.
Step 2: Download the OpenTelemetry Collector
The agent runs the OpenTelemetry Collector Contrib binary that you place on the host. Run this on the Linux host to download version 0.139.0 to /opt/signoz-collector-agent/bin/otelcol-contrib, where Foundry looks for it by default:
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -fsSL "https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.139.0/otelcol-contrib_0.139.0_linux_${ARCH}.tar.gz" | tar -xz otelcol-contrib
sudo install -D -m 755 otelcol-contrib /opt/signoz-collector-agent/bin/otelcol-contribStep 3: Create casting.yaml
Create a file named casting.yaml on the Linux host, with one document for the agent described in How it works:
apiVersion: v1alpha1
kind: CollectionAgent
metadata:
name: signoz
spec:
deployment:
mode: systemd
flavor: binary
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 examplestagingorproduction.
For every option of this casting, see the systemd binary example.
Step 4: Deploy
Run this from the directory that contains casting.yaml:
sudo foundryctl cast -f casting.yamlThis command:
- writes the collector config, the environment file and the systemd unit to
pours/collectionagent/collector/agent/; - installs them under
/etcand creates thesignoz-collector-agentuser; - enables and restarts the
signoz-collector-agentservice.
Run the same command again after editing casting.yaml.
Step 5: Verify the Collection Agent
Run this on the Linux host to check that the agent started:
sudo journalctl -u signoz-collector-agent --no-pagerThe 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 for the warnings and errors that services on the host write to the systemd journal.
Customize the Collection Agent
Every change follows the same loop: edit casting.yaml, then run sudo foundryctl cast -f casting.yaml again. Each run restarts the agent.
-
Collector settings (environment): set them in the collector's
spec(see spec fields). For example, to add ateamresource attribute to everything the agent sends:spec: collector: spec: env: OTEL_RESOURCE_ATTRIBUTES: deployment.environment=<your-environment>,team=backendVerify these values:
<your-environment>: Your deployment environment, for examplestagingorproduction.
-
Collector config (receivers, processors, pipelines): add it under
spec.collector.spec.config.data, keyedcollector/agent/agent.yaml. It merges into the generated config (see custom config files). For example, to collect host metrics every 30s:spec: collector: spec: config: data: collector/agent/agent.yaml: | receivers: hostmetrics: collection_interval: 30s -
Unit file (resource limits, capabilities): add patches under
spec.patchesagainstcollectionagent/collector/agent/signoz-collector-agent.service. A[Service]directive's path is/Service/<Directive>. For example, to cap the agent at half a CPU:spec: patches: - target: collectionagent/collector/agent/signoz-collector-agent.service operations: - op: add path: /Service/CPUQuota value: 50%Take the target and paths from the files under
pours/. Each run regenerates them, so keep every change incasting.yaml.
Troubleshooting
sudo cannot find foundryctl
In Step 4, sudo foundryctl cast -f casting.yaml stops with sudo: foundryctl: command not found.
Cause: the installer from Step 1 puts foundryctl in ~/.local/bin (or $XDG_BIN_HOME when it is set), which is not on the PATH that sudo uses.
Fix: run foundryctl through sudo with your current PATH, from the directory that contains casting.yaml:
sudo env "PATH=$PATH" foundryctl cast -f casting.yamlTo make foundryctl available to sudo for every later command, install it into /usr/local/bin instead:
curl -fsSL https://signoz.io/foundry.sh | sudo bash -s -- -d /usr/local/binAfter the fix, the command installs the agent, and Step 5 shows Everything is ready.
foundryctl cast stops with binary not found
In Step 4, sudo foundryctl cast -f casting.yaml stops with otelcol-contrib binary not found at "/opt/signoz-collector-agent/bin/otelcol-contrib", before it installs anything under /etc.
Cause: the collector binary is not at that path.
Fix: run Step 2 again, or set the binary's path as Collector binary in another location? in Step 3 shows, then run Step 4 again.
After the fix, Step 5 shows Everything is ready.
foundryctl cast refuses the collector's settings
In Step 4, sudo foundryctl cast -f casting.yaml stops with failed to enrich molding collector, followed by one of these:
spec.collector.spec.enabled is false, the CollectionAgent kind requires an enabled collectorspec.collector.spec.cluster.replicas is 2, an agent runs once per host
Cause: the casting turns the collector off or asks for more than one agent. The agent runs once on each host.
Fix: remove enabled and cluster.replicas from spec.collector.spec, then run Step 4 again.
After the fix, Step 5 shows Everything is ready.
The agent logs at least one endpoint must be specified
In Step 5, sudo journalctl -u signoz-collector-agent --no-pager shows exporters::otlphttp/signoz: at least one endpoint must be specified, and systemd keeps restarting the agent.
Cause: the casting sets no SIGNOZ_INGESTION_ENDPOINT under spec.collector.spec.env.
Fix: add it as in Step 3, then run Step 4 again.
After the fix, Step 5 shows Everything is ready.
The agent logs bind: address already in use
In Step 5, sudo journalctl -u signoz-collector-agent --no-pager shows listen tcp 127.0.0.1:8888: bind: address already in use, or the same error for 0.0.0.0:13133, 0.0.0.0:4317, or 0.0.0.0:4318, and systemd keeps restarting the agent.
Cause: another process on the host holds the port, such as the otelcol-contrib service from the OpenTelemetry Collector package or a self-hosted SigNoz on the same host.
Fix: remove the old collector as Migrate to Foundry shows, or move the agent's ports as Run on the same host as self-hosted SigNoz shows, then run Step 4 again.
After the fix, Step 5 shows Everything is ready.
foundryctl cast rejects a patch
In Step 4, sudo foundryctl cast -f casting.yaml stops before it installs the agent, with failed to apply patch for target "<target>" followed by one of these:
patch target "<target>" did not match any generated materialdoc is missing path: <path>: missing valuedoc is missing key: <path>: missing valueunable to remove nonexistent key: <key>: missing valuejson patch on blob material "<target>" is not supported
Cause: the patch's target or path does not exist in what Foundry generates. Patches apply to agent.yaml and the unit file; set the agent's variables under spec.collector.spec.env.
Fix: remove the patch, then run this from the directory that contains casting.yaml:
sudo foundryctl forge -f casting.yamlTake the target and path from the files under pours/collectionagent/, add the patch back, then run Step 4 again.
After the fix, Step 5 shows Everything is ready.
Install on macOS
On macOS, you run the OpenTelemetry Collector from its release tarball. Run every command in Terminal, in the directory where you keep the collector binary.
Step 1: Download the tarball
Run this to download version 0.139.0 for your Mac:
ARCH=$(uname -m | sed 's/x86_64/amd64/')
curl -fsSL -O "https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.139.0/otelcol-contrib_0.139.0_darwin_${ARCH}.tar.gz"Step 2: Extract the tarball
Run this in the same shell as Step 1:
tar -xzf otelcol-contrib_0.139.0_darwin_${ARCH}.tar.gz otelcol-contribThis writes the collector binary otelcol-contrib to the current directory.
Step 3: Create the collector config
Create config.yaml in the same directory, with this content:
receivers:
otlp/grpc:
protocols:
grpc:
endpoint: 0.0.0.0:4317
max_recv_msg_size_mib: 16
otlp/http:
protocols:
http:
endpoint: 0.0.0.0:4318
hostmetrics:
collection_interval: 60s
scrapers:
cpu: {}
memory: {}
disk: {}
filesystem:
exclude_fs_types:
match_type: strict
fs_types:
- autofs
exclude_mount_points:
match_type: regexp
mount_points:
- /dev/*
- ^/System/Volumes/(Preboot|VM|Update|xarts|iSCPreboot|Hardware)$
network:
exclude:
match_type: regexp
interfaces:
- ^lo0$
- ^utun\d+$
- ^awdl\d+$
- ^llw\d+$
- ^bridge\d+$
- ^vmenet\d+$
- ^anpi\d+$
- ^ap\d+$
- ^gif\d+$
- ^stf\d+$
load: {}
paging: {}
process:
mute_process_all_errors: true
processes: {}
system: {}
processors:
memory_limiter:
check_interval: 5s
limit_mib: 4000
spike_limit_mib: 800
resourcedetection:
detectors: [env, ec2, gcp, azure, system]
timeout: 2s
override: false
system:
hostname_sources: [os]
resource_attributes:
host.id:
enabled: true
batch:
send_batch_size: 1000
send_batch_max_size: 2048
timeout: 10s
exporters:
otlphttp/signoz:
endpoint: ${env:SIGNOZ_INGESTION_ENDPOINT}
headers:
signoz-ingestion-key: ${env:SIGNOZ_INGESTION_KEY}
extensions:
health_check:
endpoint: 0.0.0.0:13133
path: /healthz
service:
extensions: [health_check]
pipelines:
traces:
receivers: [otlp/http, otlp/grpc]
processors: [memory_limiter, resourcedetection, batch]
exporters: [otlphttp/signoz]
metrics:
receivers: [otlp/http, otlp/grpc, hostmetrics]
processors: [memory_limiter, resourcedetection, batch]
exporters: [otlphttp/signoz]
logs:
receivers: [otlp/http, otlp/grpc]
processors: [memory_limiter, resourcedetection, batch]
exporters: [otlphttp/signoz]Step 4: Run the collector
Run this to set the agent's environment and start it in the background:
export SIGNOZ_INGESTION_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
export SIGNOZ_INGESTION_KEY="<your-ingestion-key>"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=<your-environment>"
nohup ./otelcol-contrib --config ./config.yaml > otelcol-output.log 2>&1 & echo "$!" > otel-pidVerify these values:
<region>: Your SigNoz Cloud region.<your-ingestion-key>: Your SigNoz Cloud ingestion key.<your-environment>: Your deployment environment, for examplestagingorproduction.
The agent runs until you stop it, log out, or restart the Mac. It writes its logs to otelcol-output.log and its process ID to otel-pid.
Step 5: Verify the Collection Agent
Run this to check that the agent started:
tail -n 20 otelcol-output.logThe logs should include a line similar to the following:
... Everything is ready. Begin running and processing data.In SigNoz, open Infrastructure Monitoring > Hosts: your Mac appears under its host name as data arrives.
Customize the Collection Agent
Every change follows the same loop: edit config.yaml, then stop the agent and run Step 4 again:
kill "$(cat otel-pid)"The configure guide shows what to add to config.yaml for each change.
Troubleshooting
The agent logs at least one endpoint must be specified
In Step 5, otelcol-output.log shows exporters::otlphttp/signoz: at least one endpoint must be specified, and the agent exits.
Cause: SIGNOZ_INGESTION_ENDPOINT is not set in the shell that started the agent.
Fix: run Step 4 again, with its export lines, in the same shell.
After the fix, Step 5 shows Everything is ready.
The agent logs bind: address already in use
In Step 5, otelcol-output.log shows listen tcp 127.0.0.1:8888: bind: address already in use, or the same error for 0.0.0.0:13133, 0.0.0.0:4317, or 0.0.0.0:4318, and the agent exits.
Cause: another process on the Mac holds the port, such as a collector you started earlier or a self-hosted SigNoz on the same Mac.
Fix: find the process that holds the port, for example 4317:
sudo lsof -nP -iTCP:4317 -sTCP:LISTENStop it, or move the agent's ports as Run on the same host as self-hosted SigNoz shows, then run Step 4 again.
After the fix, Step 5 shows Everything is ready.
Install on Windows with the MSI
The OpenTelemetry Collector MSI installs the agent as the otelcol-contrib Windows service, which runs as LocalSystem and starts at boot. Run every command in PowerShell as Administrator.
Step 1: Install the MSI
Run this to download version 0.139.0 and install it:
curl.exe -fsSL -o "$env:TEMP\otelcol-contrib.msi" "https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.139.0/otelcol-contrib_0.139.0_windows_x64.msi"
(Start-Process msiexec.exe -Wait -PassThru -ArgumentList "/i `"$env:TEMP\otelcol-contrib.msi`" /qn /norestart").ExitCodeThe second command prints 0 when the install succeeds. The MSI installs otelcol-contrib.exe and a default config.yaml in C:\Program Files\OpenTelemetry Collector\, and starts the service. The service reads that config.yaml.
Step 2: Replace the collector config
Run this to replace the service's config.yaml:
Set-Content -Encoding ascii -Path 'C:\Program Files\OpenTelemetry Collector\config.yaml' -Value @'
receivers:
otlp/grpc:
protocols:
grpc:
endpoint: 0.0.0.0:4317
max_recv_msg_size_mib: 16
otlp/http:
protocols:
http:
endpoint: 0.0.0.0:4318
hostmetrics:
collection_interval: 60s
scrapers:
cpu: {}
memory: {}
disk: {}
filesystem: {}
network: {}
load: {}
paging: {}
process:
mute_process_all_errors: true
system: {}
processors:
memory_limiter:
check_interval: 5s
limit_mib: 4000
spike_limit_mib: 800
resourcedetection:
detectors: [env, ec2, gcp, azure, system]
timeout: 2s
override: false
system:
hostname_sources: [os]
resource_attributes:
host.id:
enabled: true
batch:
send_batch_size: 1000
send_batch_max_size: 2048
timeout: 10s
exporters:
otlphttp/signoz:
endpoint: ${env:SIGNOZ_INGESTION_ENDPOINT}
headers:
signoz-ingestion-key: ${env:SIGNOZ_INGESTION_KEY}
extensions:
health_check:
endpoint: 0.0.0.0:13133
path: /healthz
service:
extensions: [health_check]
pipelines:
traces:
receivers: [otlp/http, otlp/grpc]
processors: [memory_limiter, resourcedetection, batch]
exporters: [otlphttp/signoz]
metrics:
receivers: [otlp/http, otlp/grpc, hostmetrics]
processors: [memory_limiter, resourcedetection, batch]
exporters: [otlphttp/signoz]
logs:
receivers: [otlp/http, otlp/grpc]
processors: [memory_limiter, resourcedetection, batch]
exporters: [otlphttp/signoz]
'@Step 3: Set the environment and restart
Run this to set the service's environment and restart it:
New-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Services\otelcol-contrib' -Name Environment -PropertyType MultiString -Force -Value @(
'SIGNOZ_INGESTION_ENDPOINT=https://ingest.<region>.signoz.cloud:443'
'SIGNOZ_INGESTION_KEY=<your-ingestion-key>'
'OTEL_RESOURCE_ATTRIBUTES=deployment.environment=<your-environment>'
) | Out-Null
Restart-Service otelcol-contribVerify these values:
<region>: Your SigNoz Cloud region.<your-ingestion-key>: Your SigNoz Cloud ingestion key.<your-environment>: Your deployment environment, for examplestagingorproduction.
The environment variables go in the otelcol-contrib service's Environment registry value.
Step 4: Verify the Collection Agent
Run this to check that the service started:
(Get-Service otelcol-contrib).Status
Get-WinEvent -ProviderName otelcol-contrib -MaxEvents 20 | Select-Object -ExpandProperty MessageThe first command prints Running, and the events should include a message 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.
Customize the Collection Agent
Every change follows the same loop: edit C:\Program Files\OpenTelemetry Collector\config.yaml, then restart the service:
Restart-Service otelcol-contribThe configure guide shows what to add to config.yaml for each change. To change an environment variable, run Step 3 again with every variable the agent needs.
Troubleshooting
The MSI install prints a code other than 0
In Step 1, the install command prints a code other than 0, such as 1603, and C:\Program Files\OpenTelemetry Collector\ has no config.yaml.
Cause: the MSI starts the service with its default config, which needs the ports in the prerequisites, and another process on the host holds one of them, such as a self-hosted SigNoz or a collector you started yourself. When the service cannot start, the install is rolled back.
Fix: stop the other process and run Step 1 again, or install the agent manually.
After the fix, Step 1 prints 0.
The agent logs at least one endpoint must be specified
In Step 3, Restart-Service otelcol-contrib fails, and the events from Step 4 show exporters::otlphttp/signoz: at least one endpoint must be specified.
Cause: the service's Environment value sets no SIGNOZ_INGESTION_ENDPOINT.
Fix: run Step 3 again with every variable the agent needs, including SIGNOZ_INGESTION_ENDPOINT.
After the fix, Step 4 shows Running and Everything is ready.
The agent logs Only one usage of each socket address
In Step 3, Restart-Service otelcol-contrib fails, and the events from Step 4 show listen tcp 127.0.0.1:8888: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted., or the same error for 0.0.0.0:13133, 0.0.0.0:4317, or 0.0.0.0:4318.
Cause: another process on the host holds the port, such as a collector you started yourself or a self-hosted SigNoz on the same host.
Fix: find the process that holds the port, for example 4317:
Get-Process -Id (Get-NetTCPConnection -LocalPort 4317 -State Listen).OwningProcessStop it, or move the agent's ports as Run on the same host as self-hosted SigNoz shows, then run Restart-Service otelcol-contrib.
After the fix, Step 4 shows Running and Everything is ready.
Install on Windows manually
You run the OpenTelemetry Collector from its release tarball. Run every command in PowerShell, in the folder where you keep the collector binary.
Step 1: Download the tarball
Run this to download version 0.139.0:
curl.exe -fsSL -o otelcol-contrib_0.139.0_windows_amd64.tar.gz "https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.139.0/otelcol-contrib_0.139.0_windows_amd64.tar.gz"Step 2: Extract the tarball
Run this in the same PowerShell session:
tar.exe -xzf otelcol-contrib_0.139.0_windows_amd64.tar.gz otelcol-contrib.exeThis writes the collector binary otelcol-contrib.exe to the current folder.
Step 3: Create the collector config
Run this to create config.yaml in the same folder:
Set-Content -Encoding ascii -Path .\config.yaml -Value @'
receivers:
otlp/grpc:
protocols:
grpc:
endpoint: 0.0.0.0:4317
max_recv_msg_size_mib: 16
otlp/http:
protocols:
http:
endpoint: 0.0.0.0:4318
hostmetrics:
collection_interval: 60s
scrapers:
cpu: {}
memory: {}
disk: {}
filesystem: {}
network: {}
load: {}
paging: {}
process:
mute_process_all_errors: true
system: {}
processors:
memory_limiter:
check_interval: 5s
limit_mib: 4000
spike_limit_mib: 800
resourcedetection:
detectors: [env, ec2, gcp, azure, system]
timeout: 2s
override: false
system:
hostname_sources: [os]
resource_attributes:
host.id:
enabled: true
batch:
send_batch_size: 1000
send_batch_max_size: 2048
timeout: 10s
exporters:
otlphttp/signoz:
endpoint: ${env:SIGNOZ_INGESTION_ENDPOINT}
headers:
signoz-ingestion-key: ${env:SIGNOZ_INGESTION_KEY}
extensions:
health_check:
endpoint: 0.0.0.0:13133
path: /healthz
service:
extensions: [health_check]
pipelines:
traces:
receivers: [otlp/http, otlp/grpc]
processors: [memory_limiter, resourcedetection, batch]
exporters: [otlphttp/signoz]
metrics:
receivers: [otlp/http, otlp/grpc, hostmetrics]
processors: [memory_limiter, resourcedetection, batch]
exporters: [otlphttp/signoz]
logs:
receivers: [otlp/http, otlp/grpc]
processors: [memory_limiter, resourcedetection, batch]
exporters: [otlphttp/signoz]
'@Step 4: Run the collector
Run this to set the agent's environment and start it in the background:
$env:SIGNOZ_INGESTION_ENDPOINT = 'https://ingest.<region>.signoz.cloud:443'
$env:SIGNOZ_INGESTION_KEY = '<your-ingestion-key>'
$env:OTEL_RESOURCE_ATTRIBUTES = 'deployment.environment=<your-environment>'
$collector = Start-Process -FilePath .\otelcol-contrib.exe -ArgumentList '--config', '.\config.yaml' -RedirectStandardError otelcol-output.log -WindowStyle Hidden -PassThru
$collector.Id | Set-Content otel-pidVerify these values:
<region>: Your SigNoz Cloud region.<your-ingestion-key>: Your SigNoz Cloud ingestion key.<your-environment>: Your deployment environment, for examplestagingorproduction.
The agent runs until you stop it, sign out, or restart the host. It writes its logs to otelcol-output.log and its process ID to otel-pid.
Step 5: Verify the Collection Agent
Run this to check that the agent started:
Get-Content otelcol-output.log -Tail 20The 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.
Customize the Collection Agent
Every change follows the same loop: edit config.yaml, then stop the agent and run Step 4 again:
Stop-Process -Id (Get-Content otel-pid)The configure guide shows what to add to config.yaml for each change.
Troubleshooting
The agent logs at least one endpoint must be specified
In Step 5, otelcol-output.log shows exporters::otlphttp/signoz: at least one endpoint must be specified, and the agent exits.
Cause: SIGNOZ_INGESTION_ENDPOINT is not set in the PowerShell session that started the agent.
Fix: run Step 4 again, with its $env: lines, in the same session.
After the fix, Step 5 shows Everything is ready.
The agent logs Only one usage of each socket address
In Step 5, otelcol-output.log shows listen tcp 127.0.0.1:8888: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted., or the same error for 0.0.0.0:13133, 0.0.0.0:4317, or 0.0.0.0:4318, and the agent exits.
Cause: another process on the host holds the port, such as the otelcol-contrib service from the OpenTelemetry Collector MSI or a self-hosted SigNoz on the same host.
Fix: find the process that holds the port, for example 4317:
Get-Process -Id (Get-NetTCPConnection -LocalPort 4317 -State Listen).OwningProcessStop it, or move the agent's ports as Run on the same host as self-hosted SigNoz shows, then run Step 4 again.
After the fix, Step 5 shows Everything is ready.
Send data from your applications
Host metrics flow as soon as the agent is running, and on Linux so do the warnings and errors in the systemd journal. To send traces, metrics, and logs from your applications through the agent, see Send Data from Applications to Collector on VM.
