Promenade

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:

Services that are not web servers, and thus cannot expose an HTTP endpoint for Prometheus to scrape.
Web servers that are forking (like Unicorn), and thus cannot be reliably scraped by Prometheus.
Web servers in complex deployment schemes that make it impractical for Prometheus to scrape all of the servers.
Services that are currently using StatsD and want to minimally change their implementation while also getting support for the full Prometheus data model.
Services whose developers are not sold on the Prometheus pull model of metrics and are frustrated by the paradigm of the official solutions.

Running Promenade

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

Sending Metrics to Promenade over UDP

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:

a name (following the Prometheus best practices for naming metrics)
optionally followed by a group of one or more labels (in the same format as in the Prometheus text exposition format)
followed by a colon character (:)
followed by a value that can be parsed as a floating point number
followed by a pipe character (|)
followed by a single "suffix" character that corresponds to the metric type (g, c, or s).

Scraping Metrics from Promenade over HTTP

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.

Metric Types (by suffix)

|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.

Environment Variables

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).