More prescriptive guidance on metric naming

[jmacd]

The metric specification should include normative statements about naming metric instruments, including:

• When to use labels instead of components in a name?
• Avoid units in the name
• Use of plural vs singular (latencies or latency)?
• OpenMetrics guidance
• Name-spacing instruments.

This was one of the "TODOs" mentioned mentioned in #598.

[tedpennings]

I'm going to be working on this in the next few days and will post a draft

[tedpennings]

open-telemetry/oteps#108 for the spec mentioned above

[justinfoote]

I see this was assigned to me this morning. Here's my thinking.
Several of the line items in this issue have been addressed by #937.

When to use labels instead of components in a name?

general-guidelines

Metric names and labels exist within a single universe and a single hierarchy. Metric names and labels MUST be considered within the universe of all existing metric names. When defining new metric names and labels, consider the prior art of existing standard metrics and metrics from frameworks/libraries.
...
"As a rule of thumb, aggregations over all the dimensions of a given metric SHOULD be meaningful," as Prometheus recommends.

Avoid units in the name

general-guidelines

Conventional metrics or metrics that have their units included in OpenTelemetry metadata (e.g. metric.WithUnit in Go) SHOULD NOT include the units in the metric name. Units may be included when it provides additional meaning to the metric name. Metrics MUST, above all, be understandable and usable.

Name-spacing instruments.

general-guidelines

Associated metrics SHOULD be nested together in a hierarchy based on their usage. Define a top-level hierarchy for common metric categories: for OS metrics, like CPU and network; for app runtimes, like GC internals. Libraries and frameworks should nest their metrics into a hierarchy as well. This aids in discovery and adhoc comparison. This allows a user to find similar metrics given a certain metric.
The hierarchical structure of metrics defines the namespacing. Supporting OpenTelemetry artifacts define the metric structures and hierarchies for some categories of metrics, and these can assist decisions when creating future metrics.

[justinfoote]

I'll address these (probably in two separate PRs):

Use of plural vs singular (latencies or latency)?

This seems straightforward.
It looks like we use the singular form for mass nouns like utilization, usage, and duration.
And we use the pluralized form for count nouns like operations, packets, and messages.

OpenMetrics guidance

The way I see it, there are two pieces that we ought to give guidance on here.

1. Receiving a prometheus style metric that needs to be exported using OpenTelemetry

• I think this can be straightforward. We will suggest that we don't mutate the name or attributes of such a metric.

2. Exposing an OpenTelemetry metric using the prometheus exposition format.

• This is less straightforward. I'll follow up with another comment on this issue with open questions (so they don't get buried in this wall of text).
• I'd love input on what other guidance we need for OpenMetrics

[justinfoote]

Open questions about OpenMetrics guidance:

• I'm making the assumption right now that when we say OpenMetrics guidance, we're really describing interoperability with Prometheus. Is this an incorrect assumption?
• Should we convert dots to underscores or colons?
• Should we attempt to append units to the end of metric names?
• Should we require that implementors convert units to the prometheus-accepted base units?