Introduction

prometheus-client-c is a small suite of Prometheus client libraries targeted for the C programming language. In this brief tutorial you will learn how to create and register metrics, update metric samples, and expose metrics over HTTP.

Creating and Registering Metrics

prometheus-client-c supports the following metric types:

To get started using one of the metric types, declare the metric at file scope. For example:

#incldue "prom.h"
prom_counter_t *my_counter;

Next, create a metric initialization function. You can create the metric and register it with the default metric collector registry in one chain of functions. A metric collector is responsible for collecting metrics and returning them. A metric collector registry is declared in global scope and contains metric collectors. More on this later...

To create a metric and register it with the default metric collector registry in one shot, you may chain the metric constructor into the prom_collector_registry_must_register_metric function. For example:

void foo_metric_init(void) {
  my_counter = prom_collector_registry_must_register_metric(prom_counter_new("my_counter", "counts things", 0, NULL));
}

The first argument to prom_counter_new is the counter name. The second argument is the counter description. The third argument is the number of metric labels. In this case, we will only have one metric sample for this metric so we pass 0 to specify that no labels will be used. The 4th argument is an array of strings storing the metric labels. Since we have none, we pass NULL. A call to foo_metric_init within the program's main function will initialize the metrics for the file we just created to the default prometheus metric collector registery called PROM_COLLECTOR_REGISTRY_DEFAULT

Updating Metric Sample Values

Now that we have a metric configured for creation and registration, we can update our metric within any of the functions of the file in which it was declared. For example:

void my_lib_do_something(void) {
  printf("I did a really important thing!\n");
  prom_counter_inc(my_counter, NULL);
}

This function will increment the default metric sample for my_counter. Since we are not using metric labels, we pass NULL as the second argument.

Program Initialization

At the start of the program's main function you need to do two things:

Initialize the default metric collector registry:

prom_collector_registry_default_init();

For each file containing prometheus metrics, call its corresponding metric initialization function

foo_metric_init()

After initialization is complete, you may proceed to do work and update your metrics.

Metric Exposition Over HTTP

Todo:: Describe how to use libpromhttp to expose metrics over HTTP

Where to Go From Here?

Take a look at the Files tab in this documentation site for more information about the public API available to you. Also, you can take a look at the examples directory at the Github repository for inspiration.