Counter with labels not initialized

[davidgiga1993]

When creating a new counter with label, it has by default no value:

private static final Counter reportMetrics = Counter.build().labelNames("level")
            .name("vulnerabilities_report")
            .help("Number of scheduled vulnerability reports").register();

# HELP vulnerabilities_report_total Number of scheduled vulnerability reports
# TYPE vulnerabilities_report_total counter

Only after the first call to .inc() the counter value is set:

vulnerabilities_report_total{level="test",} 1.0
# HELP vulnerabilities_report_created Number of scheduled vulnerability reports
# TYPE vulnerabilities_report_created gauge
vulnerabilities_report_created{level="test",} 1.614931325367E9

According to the prometheus spec, a counter MUST always start with 0: https://prometheus.io/docs/instrumenting/writing_clientlibs/#counter

What is the expected way to initialize a counter with labels? In my use case I know all the labels before.

[fstab]

No worries, the time window before the counter exists is treated as if it is zero in Prometheus queries like rate(), so it is ok if the counter does not show up while it's zero. This is also very common, because in many cases label values are not known in advance, and then you cannot initialize counters anyways.

If you know the label values in advance and want to see your counter from the start, you could do it like this:

reportMetrics.labels("test").inc(0);

However, that should not be necessary.

Regarding the documentation: I would argue your counter does start at 0. Therefore it has the value 1 after the first inc(). This does not mean that the value 0 must be explicitly scraped before the counter goes to 1.

[davidgiga1993]

Actually I noticed this because the increase() function did not work as expected because of that after an application restart: The counter was 1 before, I restart the app, the value is now missing, I increment to 1, and increase is 0. It's an edge case but shows to me that "no value" is different than 0

[fstab]

True, in that case it really makes a difference. I had cases with larger numbers in mind, where this doesn't matter. Anyways, if you need this just call reportMetrics.labels("test").inc(0) on application startup and the counter will be there from the start initialized to zero.

In general you should not rely on that every single call is recorded. For example, if your application restarts, all calls between the last Prometheus scrape and the restart will be lost.

[davidgiga1993]

In our case it's a counter to track long scheduled jobs which occur every 24h. So the Prometheus scrape happens for sure more often. But initializing with inc(0) did the trick, thanks!

[zzvara]

@fstab For us, the following code piece that would initialize the value to 0 in order to force a metric to appear under /metrics does not work:

implicit class advancedPrometheusCounter(counter: Counter) {
  def initializeToZero: Counter = {
    counter.inc(0.0)
    counter
  }
}

val operationSuccess: Counter = Counter.build()
  .name(operationSuccessName)
  .help("Success counts.")
  .register()
  .initializeToZero

Counters still do not show up until they are incremented to 1. Should counter.inc(0.0) work after the call to register()? If so, then there must be some other problem in the asynchronicity of how the Prometheus Client is orchestrated in our code.

[fstab]

The issue that counters need to be incremented before they show up is just relevant if the counters use labels. This is because the Prometheus client library cannot know which label values you are going to use, and therefore it cannot show counters with labels if you have never incremented them.

Your counter is a counter without labels. It should be present after calling register(). I tried it in Java like this:

    Counter counter = Counter.build()
        .name("operation_success")
        .help("Success counts.")
        .register();

The counter is available:

# HELP operation_success_total Success counts.
# TYPE operation_success_total counter
operation_success_total 0.0