signoz-agent

Overview

SigNoz Agent is a lightweight OpenTelemetry collector companion for signoz-aio.
[center][color=#ff8c00]JSONbored Verified Companion Template[/color][/center]

This Unraid template runs a separate collector that can receive local application telemetry, scrape optional Prometheus targets, collect optional host metrics, collect optional Docker metrics, and tail optional Docker container logs before forwarding telemetry to your main SigNoz endpoint.

When to use this:
Use signoz-agent on remote Unraid servers, separate Docker hosts, or any machine where you want collection separated from the main signoz-aio backend. If you only need same-box collection on the server running signoz-aio, the built-in local host agent inside signoz-aio is usually simpler.

Initial Setup:

Enter your SigNoz OTLP endpoint. For signoz-aio on another host, use HOST_OR_IP:4317 with the default gRPC exporter.
Click Apply.
Point local apps at this agent on OTLP gRPC port 4317 or OTLP HTTP port 4318.
Optional: enable host metrics, Docker metrics, Docker logs, or Prometheus targets in Advanced View and explicitly set the matching mounts or target list.

Security Note: Host root, Docker socket, and Docker log mounts are blank by default. Enable only the collection sources you need. Docker socket access can expose Docker control access to this collector container.

Requirements

Requires a reachable SigNoz OTLP endpoint, usually your main signoz-aio instance or a remote SigNoz deployment. If signoz-agent is installed on the same Unraid host as signoz-aio, the default 4317 and 4318 host ports will conflict unless one template is adjusted. Host root, Docker socket, and Docker log mounts are blank by default; explicitly configure only the host access you need. Mounting /var/run/docker.sock can expose Docker control access to the collector container.

Runtime arguments

Network: bridge
Shell: sh
Privileged: false

Template configuration

SigNoz OTLP EndpointVariable

Required. Destination SigNoz OTLP endpoint. For signoz-aio on another host with the default gRPC exporter, use HOST_OR_IP:4317. For HTTP/protobuf, use an http:// or https:// endpoint ending at the OTLP HTTP listener.

Target: SIGNOZ_AGENT_ENDPOINT

OTLP gRPC PortPorttcp

Local OTLP gRPC receiver port for apps and collectors that send telemetry to this agent.

Target: 4317
Default: 4317
Value: 4317

OTLP HTTP PortPorttcp

Local OTLP HTTP receiver port for apps and collectors that send telemetry to this agent.

Target: 4318
Default: 4318
Value: 4318

AppData - SigNoz AgentPathrw

Persistent root for generated collector configuration, status, and diagnostics.

Target: /appdata
Default: /mnt/user/appdata/signoz-agent
Value: /mnt/user/appdata/signoz-agent

TimezoneVariable

Container timezone.

Target: TZ
Default: UTC
Value: UTC

[Exporter] ProtocolVariable

Advanced. Export protocol used to forward telemetry to SigNoz. Use grpc for signoz-aio 4317 and http/protobuf for SigNoz Cloud or 4318-style endpoints.

Target: SIGNOZ_AGENT_PROTOCOL
Default: grpc|http/protobuf
Value: grpc

[Exporter] Insecure TLSVariable

Advanced. Set true for plain-text or self-hosted gRPC endpoints without TLS. Set false for trusted TLS endpoints.

Target: SIGNOZ_AGENT_INSECURE
Default: true|false
Value: true

[Exporter] HeadersVariable

Advanced. Optional comma-separated exporter headers in key=value form. Values are masked because headers may contain credentials.

Target: SIGNOZ_AGENT_HEADERS

[Exporter] SigNoz Ingestion KeyVariable

Advanced. Optional SigNoz ingestion key. This is added as the signoz-ingestion-key header and is masked.

Target: SIGNOZ_AGENT_INGESTION_KEY

[Collector] Log LevelVariable

Advanced. OpenTelemetry collector log level.

Target: SIGNOZ_AGENT_LOG_LEVEL
Default: info|debug|warn|error
Value: info

[Collector] Resource AttributesVariable

Advanced. Comma-separated resource attributes added to telemetry, for example host.name=unraid-remote,service.namespace=homelab.

Target: SIGNOZ_AGENT_RESOURCE_ATTRIBUTES

[Collector] Deployment EnvironmentVariable

Advanced. Optional deployment.environment resource attribute such as homelab, production, or staging.

Target: SIGNOZ_AGENT_DEPLOYMENT_ENVIRONMENT

[Collector] Batch Send SizeVariable

Advanced. Collector batch send size.

Target: SIGNOZ_AGENT_BATCH_SEND_SIZE
Default: 8192
Value: 8192

[Collector] Batch TimeoutVariable

Advanced. Collector batch timeout.

Target: SIGNOZ_AGENT_BATCH_TIMEOUT
Default: 5s
Value: 5s

[Collector] Memory Limit MiBVariable

Advanced. OpenTelemetry memory limiter cap in MiB.

Target: SIGNOZ_AGENT_MEMORY_LIMIT_MIB
Default: 512
Value: 512

[Receiver] gRPC Listen EndpointVariable

Advanced. Internal OTLP gRPC receiver listen endpoint.

Target: SIGNOZ_AGENT_OTLP_GRPC_ENDPOINT
Default: 0.0.0.0:4317
Value: 0.0.0.0:4317

[Receiver] HTTP Listen EndpointVariable

Advanced. Internal OTLP HTTP receiver listen endpoint.

Target: SIGNOZ_AGENT_OTLP_HTTP_ENDPOINT
Default: 0.0.0.0:4318
Value: 0.0.0.0:4318

[Receiver] Health EndpointVariable

Advanced. Collector health extension endpoint. This port is not published by default.

Target: SIGNOZ_AGENT_HEALTH_ENDPOINT
Default: 0.0.0.0:13133
Value: 0.0.0.0:13133

[Host Metrics] EnableVariable

Advanced. Enables hostmetrics collection. Requires explicitly setting the Host Root Path mount below.

Target: SIGNOZ_AGENT_ENABLE_HOST_METRICS
Default: false|true
Value: false

[Host Metrics] Host Root PathPathro

Advanced optional host metrics mount. Leave blank unless host metrics are enabled. Set to / to mount the Unraid host root read-only.

Target: /hostfs

[Host Metrics] Collection IntervalVariable

Advanced. Host metrics collection interval.

Target: SIGNOZ_AGENT_HOST_COLLECTION_INTERVAL
Default: 30s
Value: 30s

[Docker Metrics] EnableVariable

Advanced. Enables Docker container metrics. Requires explicitly setting the Docker Socket mount below.

Target: SIGNOZ_AGENT_ENABLE_DOCKER_METRICS
Default: false|true
Value: false

[Docker Metrics] Docker SocketPathro

Advanced optional Docker metrics mount. Leave blank unless Docker metrics are enabled. Mounting /var/run/docker.sock can expose Docker control access to this collector container.

Target: /var/run/docker.sock

[Docker Metrics] Collection IntervalVariable

Advanced. Docker metrics collection interval.

Target: SIGNOZ_AGENT_DOCKER_COLLECTION_INTERVAL
Default: 30s
Value: 30s

[Docker Metrics] Excluded ImagesVariable

Advanced. Optional comma-separated image names to exclude from docker_stats collection, for example pause,otel/opentelemetry-collector-contrib. Container-name-specific exclusions require custom config mode.

Target: SIGNOZ_AGENT_DOCKER_EXCLUDED_IMAGES

[Docker Logs] EnableVariable

Advanced. Enables Docker JSON log tailing. Requires explicitly setting the Docker Container Logs Path mount below.

Target: SIGNOZ_AGENT_ENABLE_DOCKER_LOGS
Default: false|true
Value: false

[Docker Logs] Docker Container Logs PathPathro

Advanced optional Docker log mount. Leave blank unless Docker logs are enabled. Set to /var/lib/docker/containers to read local Docker JSON logs.

Target: /var/lib/docker/containers

[Prometheus] TargetsVariable

Advanced. Optional comma-separated Prometheus scrape targets, for example node-exporter:9100,cadvisor:8080.

Target: SIGNOZ_AGENT_PROMETHEUS_TARGETS

[Prometheus] Metrics PathVariable

Advanced. Prometheus metrics path used for all configured simple scrape targets.

Target: SIGNOZ_AGENT_PROMETHEUS_METRICS_PATH
Default: /metrics
Value: /metrics

[Prometheus] Scrape IntervalVariable

Advanced. Prometheus scrape interval.

Target: SIGNOZ_AGENT_PROMETHEUS_SCRAPE_INTERVAL
Default: 30s
Value: 30s

[Custom Config] ModeVariable

Advanced. Use generated for the Unraid-managed config. Use custom only when mounting and managing your own collector config.

Target: SIGNOZ_AGENT_CONFIG_MODE
Default: generated|custom
Value: generated

[Custom Config] Config PathVariable

Advanced. Path inside the container to a custom OpenTelemetry collector config when custom config mode is enabled.

Target: SIGNOZ_AGENT_CUSTOM_CONFIG_PATH

Links

Template Support Docker Hub Project

Details

Repository

jsonbored/signoz-agent:latest

Registry

https://hub.docker.com/r/jsonbored/signoz-agent

Last Updated2026-05-28

First Seen2026-05-01

Run signoz-agent on Unraid.

signoz-agent is listed in Community Apps for Unraid OS. Explore Unraid to build a flexible home server, NAS, or homelab.

Explore Unraid OS