A metrics forwarder for Prometheus with UDP input and full support for the Prometheus data model.
A metrics forwarder for Prometheus that accepts UDP input in a format similar to StatsD, but with support for the proper Prometheus data model, including labels.
Conceptually, this is a best-of-both-worlds between the official Prometheus StatsD Exporter (which does not support the proper Prometheus data model) and the official Prometheus Push Gateway (which supports only synchronous HTTP input and has a limited jobs-based orientation).
Unlike both of those other solutions, Promenade is intended for long-term use, because it fills a need not met by any official solution.
Promenade is suitable for:
In many cases, the easiest way to run Promenade as a standalone service is with Docker, for which an official image is provided:
# Run promenade, exposing the UDP input on port 8126 and HTTP output on 8080.
docker run -p 8126:8126 -p 8080:8080 -d jemc/promenade
Just like with StatsD, metrics are received by Promenade as UDP packets. The default UDP listener port is 8126
.
In order to ease transition from StatsD-based instrumentation, Promenade accepts input in a format that is very similar to the StatsD input format. That is, each UDP packet should contain one or more lines that look like the following, separated by "newline" characters (\n
):
my_metric_name:88.8|g
my_metric_name{label1="FOO",label2="bar"}:99.9|g
More generally, a metric line should consist of:
:
)|
)g
, c
, or s
).Just like with every other Prometheus exporter, metrics are scraped from Promenade via periodic HTTP requests. The default HTTP server port is 8080
.
When a GET
request is sent to the /metrics
route of the HTTP server, the format of the HTTP response body will be the standard Prometheus text format. That is, each HTTP response will look like the following, with a Content-Type
of text/plain
:
# TYPE my_metric_name gauge
my_metric_name{} 88.8
my_metric_name{label1="FOO",label2="bar"} 44.4
The HTTP server also exposes a /status
route, which will always respond with status code 200
and an empty body when the service is running. This route is intended to be used as a general health check.
|g
- Gauge - an instantaneous measurement of the definitive, absolute value of something.|c
- Counter - a measurement of the relative increase of something.|s
- Summary - a single sample measurement from a distribution of samples of something.|h
- Histogram - NOT YET SUPPORTED.Promenade responds to a number of environment variables for configuration:
PROMENADE_UDP_PORT
- the UDP port to listen on (default: 8126
).PROMENADE_HTTP_PORT
- the HTTP port to listen on (default: 8080
).PROMENADE_MEMORY_HWM
- the number of megabytes to use as a rough limit for memory consumption; when the limit is surpassed, all metrics will be cleared after the next metrics scrape; if zero, metrics will never be cleared for the life of the process (default: 0
).