Clarification on metric semantic convention instrument naming

[neilfordyce]

instrument-naming suggests that

an instrument that measures passage of time should be called entity.time. For example, system.cpu.time

That seems to contradict already established conventions like http.server.request.duration.

We also say

Use count Instead of Pluralization for UpDownCounters

But then there's lots of counters which don't follow that advice elsewhere in the spec e.g. http.server.active_requests or system.network.connections

Appreciate it's experimental and guideline not a hard rule, and I generally like the advice, but I also find the contradictions confusing.

[joaopgrassi]

Agreed, the contradiction is not great. Luckily both are experimental and we can fix them still 👍

[jack-berg]

The difference between system.cpu.time and http.server.request.duration is that system.cpu.time is a counter / async counter, measuring the monotonically increasing cpu time. In contrast, http.server.request.duration is a histogram where each measurement is the duration of time passed.

I think we can update the guidance to reflect this difference:

• *.time is used to measure monotonically increasing total time
• *.duration is used to measure discrete durations

From *.time you can compute things like the rate, but there's no notion of individual measurements contributing to the total time, since that information is erased when you observe something like system.cpu.time asynchronously. From *.duration you can compute the rate as well, but can also see the number of total measurements (or rate) and do things with the distribution. So *.duration is a superset of *.time from a user's perspective. Good to call out this difference with conventions.

[danielgblanco]

Agree on the items related to *.time and *.duration. Specific to UpDownCounters, http.server.active_requests is experimental (as well as the general guidance), but considering other HTTP instrument names are stable, we should probably decide if we want to go for 1 or 2 below:

1. Follow the general advice in instrument naming and change http.server.active_requests (and other pluralised UpDownCounters) to http.server.active_request.count.
2. Change the general advice related to UpDownCounters to remove the recommendation for using count instead of pluralisation (http.server.active_requests and others could remain untouched).

IMO, I think the advice regarding the use of count could be scoped more generally to reflect it's usage to count concepts within a namespace. E.g. using system.process.count instead of system.processes makes sense semantically, but I don't think *.count gives any more indication that this instrument refers to an UpDownCounter. For instance, could I have a namespace like com.mycompany.search and a Counter like com.mycompany.search.count that reflects the count of searches while also having com.mycompany.search.results as a Counter of all results returned.

Effectively, the advice could be to use count instead of pluralisation of namespaces when the instrument is counting of concepts represented in that namespace. Not a recommendation for all Counter or UpDownCounter.