jsonbored/signoz-agent repository overview

⁠signoz-agent

signoz-agent is the lightweight OpenTelemetry Collector companion for signoz-aio⁠.

Use it on remote Unraid servers, Docker hosts, or machines where you want telemetry collection separated from the main SigNoz backend container.

⁠What It Does

signoz-agent can:

• receive OTLP gRPC telemetry on 4317
• receive OTLP HTTP telemetry on 4318
• forward traces, metrics, and logs to signoz-aio
• optionally collect host metrics
• optionally collect Docker container metrics
• optionally tail Docker container logs
• optionally scrape Prometheus targets
• optionally use custom OpenTelemetry Collector config

Host root, Docker socket, and Docker log mounts are blank by default in the Unraid template. Enable only the collection sources you need.

⁠Recommended Unraid Usage

Most users should install this through Unraid Community Applications once available.

Required beginner fields:

• SigNoz OTLP Endpoint
• AppData - SigNoz Agent
• OTLP gRPC Port
• OTLP HTTP Port

For a signoz-aio instance running on another host, use HOST_OR_IP:4317 with the default exporter protocol grpc.

If signoz-agent runs on the same Unraid host as signoz-aio, the default 4317 and 4318 host ports will conflict unless one template is adjusted.

⁠Docker Run Example

docker run -d \
  --name signoz-agent \
  --restart unless-stopped \
  -p 4317:4317 \
  -p 4318:4318 \
  -v /mnt/user/appdata/signoz-agent:/appdata \
  -e TZ=UTC \
  -e SIGNOZ_AGENT_ENDPOINT=YOUR-SIGNOZ-AIO-IP:4317 \
  -e SIGNOZ_AGENT_PROTOCOL=grpc \
  -e SIGNOZ_AGENT_INSECURE=true \
  jsonbored/signoz-agent:latest

Then point local apps or collectors at:

• http://HOST_IP:4317
• http://HOST_IP:4318

⁠Optional Host Metrics

Host metrics require an explicit host mount:

-e SIGNOZ_AGENT_ENABLE_HOST_METRICS=true \
-v /:/hostfs:ro

⁠Optional Docker Metrics

Docker metrics require an explicit Docker socket mount:

-e SIGNOZ_AGENT_ENABLE_DOCKER_METRICS=true \
-v /var/run/docker.sock:/var/run/docker.sock:ro

Mounting the Docker socket has security implications because it can expose Docker control access to the collector container.

⁠Optional Docker Logs

Docker log collection requires an explicit Docker log mount:

-e SIGNOZ_AGENT_ENABLE_DOCKER_LOGS=true \
-v /var/lib/docker/containers:/var/lib/docker/containers:ro

⁠Optional Prometheus Scraping

-e SIGNOZ_AGENT_PROMETHEUS_TARGETS=node-exporter:9100,cadvisor:8080 \
-e SIGNOZ_AGENT_PROMETHEUS_METRICS_PATH=/metrics \
-e SIGNOZ_AGENT_PROMETHEUS_SCRAPE_INTERVAL=30s

⁠Images

Published images:

• ghcr.io/jsonbored/signoz-agent
• jsonbored/signoz-agent

Tags include:

• latest
• upstream collector version, for example 0.139.0
• agent release tag, for example 0.139.0-agent.1
• commit tag, for example sha-<commit>

⁠Related Project

Use signoz-aio⁠ as the main SigNoz backend/UI/database stack.

signoz-agent is only the collection companion. It does not include the SigNoz UI, API, ClickHouse, or ZooKeeper.

⁠Security Notes

The default agent template does not mount:

• host root
• Docker socket
• Docker container logs

Those are advanced opt-in settings. Only enable the collection sources you need.

⁠Support

Issues and support:

• https://github.com/JSONbored/signoz-aio/issues⁠

Documentation and source:

• https://github.com/JSONbored/signoz-aio⁠