`system.network.connections` wrong pluralization

[braydonk]

Area(s)

No response

What's missing?

system.network.connections is an updowncounter, and as such should be named system.network.connection.count.

Describe the solution you'd like

No response

[ChrsMark]

I find the guidance to Use count instead of pluralization for UpDownCounters a bit unclear 🤔 .

Should we use .count suffix for all metrics that are of updowncounter type regardless? The specific paragraph implies that there should a namespace for the entity but here we don't have a system.network.connection.* namespace.

That also hits me at #2191 (comment) so I would appreciate a clarification.

[braydonk]

Yeah you're right, the guidance could be clearer here.

Quoting from the linked guidance:

If the value being recorded represents the count of concepts signified by the namespace then the metric should be named count

This is where the ambiguity comes in for sure; system.network.connection isn't necessarily a namespace insofar as we have no other metrics stemming from system.network.connection. We could interpret it as such and say it's a namespace with only one metric for now being .count if we think there might be others added. I can't currently think of any more metrics we might add, but perhaps it's still worth taking the .count route so that we're not locked out of any other system.network.connection.* metrics ever being added?

Something the guidance should make a bit more clear is the reasoning for a SHOULD on .count with UpDownCounters in relation to using pluralization. If the goal is to surface clearly within the name when something is UpDownCounter vs Counter then that's fine but should probably be stated explicitly. This is how I've been treating it, but litigating the guidance more closely does reveal some ambiguity.

Tagging in @open-telemetry/specs-semconv-maintainers to help resolve this.

[ChrsMark]

So based on the discussion from Monday's May 26 2025 meeting it seems that all metrics of type UpDownCounter should be suffixed with .count, right?

Latest comments on #1999 indicate that but we would potentially need to make it even more explicit in the guidance?

@braydonk @lmolkova please check me on this. Pinging @trask as well because of #1999 :).

[braydonk]

I interpreted it as the more important detail being not to pluralize UpDownCounters, but .count is the most popular alternative. However the guidance is cleared up, I hope the reasoning behind that particular decision is made clear.
(Also if the decision is to make .count suffix a SHOULD I would be fine with that too, just would like it all explained a bit better)

[trask]

I think the motivation was to share the namespace between the metric and its attributes, and then maybe in the future we could say that the metric namespace is the "default" namespace for its attributes (and so maybe treat those attributes' namespaces as optional in some contexts)

This idea came out of the pushback we got when we said that metric attributes must be globally namespaced, since many people didn't feel that was necessary for metric attributes since they were already "scoped" to a specific metric.

That said, I think I feel ok about removing the guidance to Use count instead of pluralization for UpDownCounters.

[ChrsMark]

So based on the above my initial assumption seems to be confirmed that the guidance applies only when there is an "overlap" between the namespace and the metric name. For example since system.process.* is an already existing namespace then we should use system.process.count and not system.processes.

The guidance does not enforce to use .count for all UpDownCounters and metric like k8s.deployment.desired_pods (and similar) is fine if there is no need for k8s.deployment.desired_pod.* namespace.

If that's the case I agree that we can either remove the guidance or just try to clarify its content.

I filed #2306 to explicitly decide on this.