Send StatsD Metrics to SigNoz using OpenTelemetry Collector

StatsD is a popular network daemon that listens for statistics (like counters, timers, and gauges) sent over UDP or TCP and aggregates them before forwarding to a backend. You can send custom metrics from your applications using StatsD clients to SigNoz by configuring the OpenTelemetry Collector's statsd receiver.

This guide explains how to set up the OpenTelemetry Collector to listen for StatsD metrics and send them to SigNoz.

Prerequisites

An instance of SigNoz (either Cloud or Self-Hosted)
An instance of OpenTelemetry Collector running, if not, follow the installation instructions for your environment

Send StatsD Metrics to SigNoz

Step 1: Configure the StatsD receiver

The OpenTelemetry Collector uses the StatsD receiver to ingest metrics in the StatsD format.

Add the statsd receiver to your otel-collector-config.yaml file. Make sure it listens on the desired address (default for StatsD is UDP port 8125):

otel-collector-config.yaml

receivers:
  statsd:
    endpoint: "0.0.0.0:8125"

Explanation of the fields:

endpoint: The address (host:port) where the receiver will listen for UDP StatsD packets. Use 0.0.0.0 to listen on all interfaces.

If you need to configure options like sample rates or timing mappings, you can add them to the statsd receiver.

receivers:
  statsd:
    endpoint: "0.0.0.0:8125"
    aggregation_interval: 60s
    enable_metric_type: true
    is_monotonic_counter: false
    timer_histogram_mapping:
      - statsd_type: "histogram"
        observer_type: "gauge"
      - statsd_type: "timing"
        observer_type: "histogram"

aggregation_interval: How often the receiver aggregates the received StatsD metrics before sending them out (default is 60s).
enable_metric_type: When true, the receiver emits the original StatsD metric type (counter, gauge) as a metric attribute label.
is_monotonic_counter: When true, sets all counter-type metrics received as monotonic (meaning they only ever increase).
timer_histogram_mapping: Specifies what OpenTelemetry data type to convert received timing or histogram data into. In the example above:
- StatsD histogram data is converted to an OpenTelemetry gauge (no aggregation).
- StatsD timing data is converted to an OpenTelemetry histogram (aggregated over time).

See the StatsD receiver documentation for more mapping options.

Step 2: Configure the exporter to SigNoz Cloud

If you haven't already configured your Collector to send data to SigNoz Cloud, add an otlp exporter:

otel-collector-config.yaml

exporters:
  otlp/signoz:
    endpoint: ingest.<region>.signoz.cloud:443
    tls:
      insecure: false
    headers:
      "signoz-ingestion-key": "<your-ingestion-key>"

Verify these values:

<region>: Your SigNoz Cloud region
<your-ingestion-key>: Your SigNoz ingestion key

Step 3: Enable the receiver and exporter in your pipeline

Enable both the statsd receiver and the otlp/signoz exporter in your metrics pipeline. Add them to service.pipelines.metrics. Append the receiver and exporter to your configuration like:

otel-collector-config.yaml

service:
  pipelines:
    metrics:
      receivers: [otlp, statsd] # Append statsd to your existing receivers
      exporters: [otlp/signoz]  # Ensure your exporter is included here

Step 4: Expose the StatsD port

Depending on how you deploy the OpenTelemetry Collector, you need to ensure the StatsD UDP port (8125) is accessible to your applications.

No additional port mapping is required, just ensure your firewall allows incoming UDP traffic on port 8125.

Check if the collector is listening on the port:

sudo netstat -ulnp | grep 8125

If your Collector runs in Kubernetes (e.g., using the signoz/k8s-infra Helm chart), you must expose the UDP port in the Service definition.

Update your values.yaml for the k8s-infra chart:

values.yaml

otelAgent:
  ports:
    statsd:
      enabled: true
      containerPort: 8125
      servicePort: 8125
      hostPort: 8125
      protocol: UDP

Then upgrade your Helm release:

helm upgrade my-release signoz/k8s-infra -f values.yaml

If you run the Collector via Docker, ensure you publish the UDP port using the -p flag:

docker run -d --name otel-collector \
  -v $(pwd)/otel-collector-config.yaml:/etc/otel-collector-config.yaml \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 8125:8125/udp \
  signoz/signoz-otel-collector:latest \
  --config /etc/otel-collector-config.yaml

If using docker-compose.yaml, add the port mapping:

docker-compose.yaml

services:
  otel-collector:
    image: signoz/signoz-otel-collector:latest
    ports:
      - "4317:4317"
      - "8125:8125/udp"

Step 5: Restart the OpenTelemetry Collector

After modifying the configuration file and exposing the necessary ports, restart the OpenTelemetry Collector for the changes to take effect.

Depending on your environment, you can restart the collector using the following commands:

Docker: docker restart otel-collector
VM: sudo systemctl restart signoz-otel-collector (or the respective service name)

Validate

To test if the OpenTelemetry Collector successfully receives your StatsD metrics, you can send a dummy metric using nc (netcat):

echo "custom.test.metric:1|c" | nc -w 1 -u 127.0.0.1 8125

This command sends a StatsD counter metric named custom.test.metric with a value of 1. (Make sure you replace 127.0.0.1 with your Collector instance IP if testing remotely).

Wait for the aggregation interval (e.g., 60 seconds) to pass. Then, navigate to the SigNoz UI to verify:

Navigate to Metrics Explorer.
Search for custom.test.metric.
You should see the metric data in the chart.

*Custom StatsD metric in Metrics Explorer*

Troubleshooting

If you don't see your metrics in SigNoz, check the following:

Port Configuration

Ensure that port 8125/UDP is open and accessible from your application to the OpenTelemetry Collector.

Docker: Did you map the port when starting the container? Ensure your docker run command or docker-compose.yaml includes -p 8125:8125/udp.
Kubernetes: If your Collector runs in K8s, ensure the UDP port is exposed in the Service definition and properly mapped in your otel-agent daemonset. See Configure K8s Infra for exposing additional receiver ports.
Firewall: Check if firewalls (e.g., AWS Security Groups) are allowing UDP traffic on port 8125.

Check Collector Logs

Enable debug logging on your OpenTelemetry Collector to see if it receives the stats. Merge this setting with your existing service.telemetry configuration rather than replacing it:

otel-collector-config.yaml

service:
  telemetry:
    logs:
      level: debug

Check the Collector's output for any errors related to parsing StatsD messages.

Metrics Export Errors

If metrics are received but not exported downstream, there might be an issue with your exporter configuration (keys, endpoints). Look for exporting failed errors in the OTel Collector logs. Ensure your otlp/signoz exporter is correctly pointing to your SigNoz cloud region endpoint with the valid ingestion key.

Next Steps

Now that you have your StatsD metrics flowing into SigNoz, you can use them to build custom visualizations and trigger alerts when things go wrong:

Get Help

If you need help with the steps in this topic, please reach out to us on SigNoz Community Slack.

If you are a SigNoz Cloud user, please use in product chat support located at the bottom right corner of your SigNoz instance or contact us at cloud-support@signoz.io.

Send StatsD Metrics to SigNoz using OpenTelemetry Collector

Prerequisites

Send StatsD Metrics to SigNoz

Step 1: Configure the StatsD receiver

Step 2: Configure the exporter to SigNoz Cloud

Step 3: Enable the receiver and exporter in your pipeline

Step 4: Expose the StatsD port

Step 5: Restart the OpenTelemetry Collector

Validate

Troubleshooting

Port Configuration

Check Collector Logs

Metrics Export Errors

Next Steps

Get Help

Was this page helpful?

Is this page helpful?