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.