diff --git a/specification/api-metrics-user.md b/specification/api-metrics-user.md index 02170a87f64..0f7d564d944 100644 --- a/specification/api-metrics-user.md +++ b/specification/api-metrics-user.md @@ -9,15 +9,9 @@ TODO: Add a table of contents. ## Overview -Metric instruments are the entry point for application and framework developers to instrument their code using counters, gauges, and measures. Metrics are created by calling methods on a `Meter` which is in turn created by a global `MeterFactory`. - -### Obtaining a Meter - -New `Meter` instances can be created via a `MeterFactory` and its `getMeter` method. `MeterFactory`s are generally expected to be used as singletons. Implementations -SHOULD provide a single global default `MeterFactory`. The `getMeter` method expects two string arguments: - -- `name` (required): This name must identify the instrumentation library (also referred to as integration, e.g. `io.opentelemetry.contrib.mongodb`) and *not* the instrumented library. In case an invalid name (null or empty string) is specified, a working default `Meter` implementation as a fallback is returned rather than returning null or throwing an exception. A library, implementing the OpenTelemetry API *may* also ignore this name and return a default instance for all calls if it does not support "named" functionality (e.g. an implementation which is not even observability-related). A `MeterFactory` could also return a no-op `Meter` here if application owners configure the SDK to suppress telemetry produced by this library. -- `version` (optional): Specifies the version of the instrumentation library (e.g. `semver:1.0.0`). +Metric instruments are the entry point for application and framework +developers to instrument their code using counters, gauges, and +measures. ### Metric names @@ -29,8 +23,13 @@ external systems. Metric names conform to the following syntax: 3. The first character must be non-numeric, non-space, non-punctuation 4. Subsequent characters must be belong to the alphanumeric characters, '_', '.', and '-'. -Metric names belong to a namespace. The `component` label value of the associated `Meter` serves as its namespace, allowing the same metric name to be used in multiple libraries of code, unambiguously, within the same application. -_Note: Even though this namespace could be similar or equal to the `name` provided to `MeterFactory`, these are distinct concepts and must not be used interchangeably._ +Metrics names belong to a namespace by virtue of a "Named" `Meter` +instance. A "Named" `Meter` refers to the requirement that every +`Meter` instance must have an associated `component` label, determined +statically in the code. The `component` label value of the associated +`Meter` serves as its namespace, allowing the same metric name to be +used in multiple libraries of code, unambiguously, within the same +application. Metric instruments are defined using a `Meter` instance, using a variety of `New` methods specific to the kind of metric and type of @@ -72,7 +71,7 @@ either floating point or integer inputs, see the detailed design below. Binding instruments to a single `Meter` instance has two benefits: 1. Instruments can be exported from the zero state, prior to first use, with no explicit `Register` call -2. The component name provided by the `Meter` satisfies a namespace requirement +2. The component name provided by the named `Meter` satisfies a namespace requirement The recommended practice is to define structures to contain the instruments in use and keep references only to the instruments that @@ -83,7 +82,7 @@ metric instruments statically and providing the `Meter` interface at the time of use. In this example, typical of statsd clients, existing code may not be structured with a convenient place to store new metric instruments. Where this becomes a burden, it is recommended to use -the global meter factory to construct a static `Meter`, to +the global meter factory to construct a static named `Meter`, to construct metric instruments. The situation is similar for users of Prometheus clients, where