Using the Metrics API


The Hadean Platform provides an API which can be used to output metrics from any Platform process or component. Applications using the metrics API need to include the hadean/metrics.hh header.
These metrics will be very familiar if you've used prometheus before, our API is essentially the prometheus C++ API. We have counters, gauges, families, etc.


Relating to metrics, serialisation means taking the in-memory metrics and writing them out, either to disk or network. The Hadean Platform will not automatically invoke this serialisation for you, so at regular intervals you should invoke
However, because Simulate also uses Hadean metrics, and because engine code and user code share the same metrics registry, Simulate workers and manager will already call this serialisation, so you may omit it on those processes.

Adding a Metric

There are a few pieces of code necessary to add a metric:
  1. 1.
    add some state
struct per_worker_data {
hadean::metrics::Family<hadean::metrics::Gauge>* total_entities_family;
hadean::metrics::Gauge* total_entities_metric;
  1. 1.
    add the initialisation logic
hadean::metrics::Family<hadean::metrics::Gauge>& entities_family(
hadean::metrics::Gauge& entities_metric = entities_family.Add({
{"worker_id", std::to_string(aether_state.get_worker().as_u64())}
  1. 1.
    add some logic to set or increment the counter/gauge at an appropriate point
  1. 1.
    add a call to the serialization
  1. 1.
    make sure to remove metrics if you're working with finite lifetime processes (they might die before the end of the whole program)
That's enough to have your metric available via our metrics API.
See the platform documentation for more details on how to access Metrics

Viewing your Metrics

Follow the instructions in Metrics to setup a Prometheus server with the SDK.
You can then view your metrics (while a simulation is running) by going to http://<prometheus-address>:<prometheus-port>/graph (port defaults to 9090, address might be localhost)
If you followed the snippets in this document, try typing total_entities into the query box and pressing execute. Also try checking the "stacked" box to see a stacked plot of the values for each of the workers.