prometheus_client

Description:

prometheus client

prometheus_client #


This is a simple Dart implementation of the Prometheus client
library, similar to to libraries for other languages. It supports the default metric types like
gauges, counters, summaries, or histograms. Metrics can be exported using the text format. To expose them
in your server application the package comes with the package prometheus_client_shelf to
integrate metrics with a shelf handler. In addition, it comes with some plug-in ready metrics for the Dart
runtime.
You can find the latest updates in the changelog.
Usage #
A simple usage example:
import 'dart:io';

import 'package:prometheus_client/format.dart' as format;
import 'package:prometheus_client/prometheus_client.dart';
import 'package:prometheus_client/runtime_metrics.dart' as runtime_metrics;

main() async {
// Register runtime metrics with the default metrics registry
runtime_metrics.register();

// Create a Histogram metrics without labels. Always register your metric,
// either at the default registry or a custom one.
final durationHistogram = Histogram(
name: 'http_request_duration_seconds',
help: 'The duration of http requests in seconds.',
)
..register();

// Create a metric of type counter, with a label for the requested path:
final metricRequestsCounter = Counter(
name: 'metric_requests_total',
help: 'The total amount of requests of the metrics.',
labelNames: ['path'],
)
..register();

// Create a http server
final server = await HttpServer.bind(
InternetAddress.loopbackIPv4,
8080,
);
print('Listening on localhost:${server.port}');

await for (HttpRequest request in server) {
// Measure the request duration
await durationHistogram.observeDuration(Future(() async {
// Count calls to the metric endpoint by path.
metricRequestsCounter.labels([request.uri.path]).inc();

// Output metrics in the text representation
request.response.headers.add('content-type', format.contentType);
final metrics = await CollectorRegistry.defaultRegistry.collectMetricFamilySamples();
format.write004(request.response, metrics);
await request.response.close();
}));
}
}
copied to clipboard
Start the example application and access the exposed metrics at http://localhost:8080/. For a full usage example, take
a look at example/prometheus_client_example.dart.
Metrics #
The package provides different kinds of metrics:
Counter
Counter is a monotonically increasing counter.
Counters can only be incremented, either by one or a custom amount:
final requestsCounter = Counter(
name: 'metric_requests_total',
help: 'The total amount of requests of the metrics.',
);

requestsCounter.inc();
requestsCounter.inc(64.0);
copied to clipboard
Gauge
A Gauge represents a value that can go up and down:
final gauge = Gauge(
name: 'my_metric',
help: 'Help!',
);

gauge.value = 1337.0;
gauge.inc(2.0);
gauge.dec(4.0);
copied to clipboard
Histogram
Histogram allows aggregatable distributions of events, such as request latencies.
The buckets of the histogram are customizable and support both linear and exponential buckets.
final histogram = Histogram(
name: 'my_metric',
help: 'Help!',
);

histogram.observe(20.0);
await histogram.observeDuration(() async {
// Some code
});
histogram.observeDurationSync(() {
// Some code
});
copied to clipboard
Summary
Similar to a Histogram, a Summary samples observations (usually things like request durations and response sizes). While it also provides a total count of observations and a sum of all observed values, it calculates configurable quantiles over a sliding time window.
final summary = Summary(
name: 'my_metric',
help: 'Help!',
);

summary.observe(20.0);
await summary.observeDuration(() async {
// Some code
});
summary.observeDurationSync(() {
// Some code
});
copied to clipboard
Labels
Metrics can optionally have labels. You can pass label names during metrics creation.
Later on, you can access a child metric for your label values via the labels() function.
final requestsCounter = Counter(
name: 'metric_requests_total',
help: 'The total amount of requests of the metrics.',
labelNames: ['path'],
);

requestsCounter.labels(['my/path/']).inc();
copied to clipboard
Collect
For metrics that should provide the current value during scraping, each metric type provides a collectCallback that is executed during scraping.
You can use the callback to update the metric while scraping.
The callback can either be sync, or return a Future:
final gauge = Gauge(
name: 'my_metric',
help: 'Help!',
collectCallback: (gauge) {
// Callback is executed every time the metric is collected.
// Use the function parameter to access the gauge and update
// its value.
gauge.value = 1337;
},
);
copied to clipboard
Default Metrics #
The RuntimeCollector provides a basic set of built-in metrics. However, only a limited set of
the recommended standard metrics is implemented, as Dart doesn't expose them.
Outputting Metrics #
The package comes with function for serializing the metrics into the Prometheus metrics text format:
final buffer = StringBuffer();
final metrics = await CollectorRegistry.defaultRegistry.collectMetricFamilySamples();
format.write004(buffer, metrics);
print(buffer.toString());
copied to clipboard
If you are using shelf, take a look at prometheus_client_shelf for providing a metrics
endpoint.
Features and bugs #
Please file feature requests and bugs at the issue tracker.