Small editorial observation about the Metrics Semantic Guidelines

[sebastien-rosset]

In the protobuf spec, the name of a Metric is documented as:

name of the metric, including its DNS name prefix. It must be unique.

I don't see the DNS name prefix part of a metric name being explained in the OpenTelemetry specification.

The README.md file starts with general guidelines about metric names and attribute names. Guidelines include name reuse, units and pluralization. This section does not include the word "instrument”, so a reader might assume that particular section does not cover naming conventions for instruments.

In that same README.md file, the “General Guidelines” section is followed by a section named General Metric Semantic Conventions. The title of that section has the word “metric”, but the whole section is primarily about “Instrument” naming. At that point the reader may be thinking or wondering if are there are two separate naming rules: 1) naming rules for metrics and attributes, and 2) naming rules for “instruments”. Or maybe even wondering if there is an editorial mistake. It’s a bit confusing because the word in the section title does not quite match the content of the section.

It does not help that "metric name" and "instrument name" are sometimes conflated in discussions. For example:

Semantic conventions (for metrics names) are currently defined/proposed using dots: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/metrics/semantic_conventions/http-metrics.md

The discussion refers to metric names, but the file is about instrument names.

Also, in the data model file, there is a reference to "metric name", https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/data-model.md#timeseries-model. Maybe it would help to clarify how metric names and instrument names relate to each other.

[sebastien-rosset]

Opened #3134 and #3135.