Use `total` instead of `count` in the metrics semantic conventions

[emschwartz]

What are you trying to achieve?

I am working on a project built on OTel and Prometheus (overview blog post here) and am trying to make the metrics I generate fit both OpenTelemetry and OpenMetrics as best as I can. However, there is an unfortunate and seemingly unnecessary divergence between these two standards with regard to the naming of counters.

The OTel semantic conventions say that count should be used as a suffix while OpenMetrics mandates that counters end with a total suffix. It seems silly that metrics produced with OTel and then exported to Prometheus would end up with a _count_total suffix.

I completely understand if this part of the spec is too far along to change it now. But, if not, I'd like to propose changing the recommendation to say that the word total should be used instead. Those two words are pretty close to synonymous so it doesn't seem like it would be that painful to go with the one chosen by OpenMetrics for that extra little bit of compatibility.

For what it's worth, I personally prefer the word count so I can see why OTel chose it, but I'd opt for the substantive benefit of better compatibility between the standards over that instinct.

Additional context.

The Metrics Semantic Conventions say:

Use count Instead of Pluralization

If the value being recorded represents the count of concepts signified by the namespace then the metric should be named count (within its namespace). The pluralization rule does not apply in this case.

For example if we have a namespace system.processes which contains all metrics related to the processes then to represent the count of the processes we can have a metric named system.processes.count. The suffix count here indicates that it is the count of system.processes.

OpenMetrics says:

Counter

The MetricPoint's Total Value Sample MetricName MUST have the suffix "_total".

[trask]

adding this as a JVM runtime metrics stability blocker (to decide one way or another) because of process.runtime.jvm.threads.count

[jack-berg]

@trask what is the stability status of the General Guidelines section? The document is marked "mixed", and other sections are indicated as "stable", but General Guidelines is missing a designation. Presumably its experimental?

[jack-berg]

I'm confused by the "use count instead of pluralization" rule:

If the value being recorded represents the count of concepts signified by the namespace then the metric should be named count (within its namespace). The pluralization rule does not apply in this case.

The definition of "concepts signified by the namespace" seems ambiguous. Examples are given:

• system.paging.faults - doesn't need count because presumably paging is an acceptable namespace
• system.processes.count - needs the count because somehow processes is the namespace here instead of system?

When is a namespace different that the concept being counted? Why is processes a namespace but faults is not?

Extended to this java example, why can we not think of jvm as the namespace in process.runtime.jvm.threads, and drop the count suffix?

[trask]

@trask what is the stability status of the General Guidelines section? The document is marked "mixed", and other sections are indicated as "stable", but General Guidelines is missing a designation. Presumably its experimental?

ya, I believe it should be experimental, i'll send a PR to clarify

[trask]

Extended to this java example, why can we not think of jvm as the namespace in process.runtime.jvm.threads, and drop the count suffix?

I think the difference is that if we use process.runtime.jvm.threads for the counter, then it cannot later be used as a namespace, and we cannot add something like process.runtime.jvm.threads.created (say if we wanted to track number of created threads over time).

[jack-berg]

I think the difference is that if we use process.runtime.jvm.threads for the counter, then it cannot later be used as a namespace, and we cannot add something like process.runtime.jvm.threads.created

Hmm... that could be the intent. I think I disagree. That policy encourages being conservative and including .count to preserve the ability to add additional metrics in the namespace later, even if none are currently anticipated.

I don't think it's so bad to start with process.runtime.jvm.threads, and later add process.runtime.jvm.threads.created or process.runtime.jvm.threads_created. In systems like prometheus where . is replaced with _, the distinction of a namespace would go away anyway as both *.threads.created and *.threads_created result in *_threads_created.

I propose we get rid of the "use count instead of pluralization" rule.

[emschwartz]

@reyang I think it would make sense to keep this issue open. Even if that section is marked as experimental, I'd still like to propose changing the recommendation or taking it out entirely as @jack-berg suggested.