Skip to content

Commit

Permalink
Revert api-metrics-user.md
Browse files Browse the repository at this point in the history
  • Loading branch information
arminru authored Jan 13, 2020
1 parent f6feff0 commit 7e6367c
Showing 1 changed file with 12 additions and 13 deletions.
25 changes: 12 additions & 13 deletions specification/api-metrics-user.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down

0 comments on commit 7e6367c

Please sign in to comment.