Getting Started with StatsD Receiver in AWS Distro for OpenTelemetry Collector

StatsD receiver is an agent that collects StatsD metrics and does the aggregation for a customer defined interval (default value is 60s). The aggregation interval is similar to the flush interval in StatsD. You can send counters, gauges and timer/histogram to StatsD receiver, which will send the aggregated metrics to the following workflow. For example, you can use EMF exporter to send the metrics to CloudWatch.

StatsD receiver currently supports counter, gauge and timer/histogram types. The StatsD receiver can be used as a replacement of CloudWatch agent StatsD plugin for StatsD/dogStatsD.

Enabling StatsD Receiver

To enable the StatsD receiver, add the name under the receiver section in the config file (local/config.yaml). By default, the receiver listens address localhost:8125, collects all metrics and aggregate the metrics in 60s. The transport can only be udp. (For the full list of metrics, see Available Metrics).

The following configuration collects StatsD metrics by using StatsD receiver and sends them to CloudWatch using awsemf exporter. You can set these configuration values to what works for your application. Check out SETUP section for configuring AWS Distro for OpenTelemetry Collector in Amazon Elastic Container Service.

The upstream link(StatsD receiver in OpenTelemetry): Upstream

Copy
1receivers:
2  statsd:
3    endpoint: 0.0.0.0:8125 #default
4    aggregation_interval: 60s #default
5    enable_metric_type: false #default
6    timer_histogram_mapping: #default
7      - statsd_type: "histogram" #default
8        observer_type: "gauge" #default
9      - statsd_type: "timer" #default
10        observer_type: "gauge" #default
11exporters:
12  awsemf:
13    namespace: ECS/AWSOTel/Application
14    log_group_name: '/aws/ecs/application/metrics'
15    region: 'us-west-2'
16service:
17  pipelines:
18    metrics:
19      receivers: [statsd]
20      exporters: [awsemf]

Available Metrics

General format:

<name>:<value>|<type>|@<sample-rate>|#<tag1-key>:<tag1-value>,<tag2-k/v>

Counter

<name>:<value>|c|@<sample-rate>|#<tag1-key>:<tag1-value>

It supports sample rate.

Gauge

name>:<value>|g|@<sample-rate>|#<tag1-key>:<tag1-value>

Sample rate is not supported for gauges.

Timer

<name>:<value>|ms|@<sample-rate>|#<tag1-key>:<tag1-value>

It supports sample rate.

timer_histogram_mapping is the configuration for timer/histogram. For statsd_type, you could choose timer, timing or histogram. For observer_type, you could choose gauge. When choosing gauge, StatsD receiver will send the timer/histogram metric to the downstream component as OTLP gauge without doing any aggregation.

Histogram

<name>:<value>|h|@<sample-rate>|#<tag1-key>:<tag1-value>

It supports sample rate.

timer_histogram_mapping is the configuration for timer/histogram. For statsd_type, you could choose timer, timing or histogram. For observer_type, you could choose gauge. When choosing gauge, StatsD receiver will send the timer/histogram metric to the downstream component as OTLP gauge without doing any aggregation.

Aggregation

You can set the aggregation interval using configuration parameter: aggregation_interval. The examples below mean receiving metrics in the same interval.

Counter

Example one:

statsdTestMetric1:3000|c|#mykey:myvalue statsdTestMetric1:4000|c|#mykey:myvalue

result: get the value after incrementation: 7000 (3000+4000). For counter, the same metric with different value in an interval will be incremented.

Example two:

statsdTestMetric1:3000|c|#mykey:myvalue statsdTestMetric1:20|c|@0.25|#mykey:myvalue

result: get the value after incrementation with sample rate: 3080 (3000+20/0.25). For counter, the sample rate will be calculated.

Gauge

Example one:

statsdTestMetric1:500|g|#mykey:myvalue statsdTestMetric1:400|g|#mykey:myvalue

result: get the latest value: 400. For gauge, the newest value will cover the early value.

Example two:

statsdTestMetric1:500|g|#mykey:myvalue statsdTestMetric1:+2|g|#mykey:myvalue statsdTestMetric1:-1|g|#mykey:myvalue

result: get the value after calculation: 501. For gauge, it supports plus and minus for aggregation.

Timer

Example one(use observer_type as gauge):

statsdTestMetric1:500|ms|#mykey:myvalue statsdTestMetric1:400|ms|#mykey:myvalue

result: send two OTLP gauge metrics to the downstream component. The first one has the value 500, the second one has the value 400.

Histogram

Example one(use observer_type as gauge):

statsdTestMetric1:500|h|#mykey:myvalue statsdTestMetric1:400|h|#mykey:myvalue

result: send two OTLP gauge metrics to the downstream component. The first one has the value 500, the second one has the value 400.

other Configuration Parameters

enable_metric_type

The default value is false, enable the statsd receiver to be able to emit the metric type(gauge, counter, timer(in the future), histogram(in the future)) as a label.

Example:

statsdTestMetric1:500|g|#mykey:myvalue with enable_metric_type: true will add metric_type: gauge label to the downstream.