mirror of
https://github.com/open-telemetry/opentelemetry-go.git
synced 2024-12-24 20:14:40 +02:00
Document instrument name requirements (#5435)
Fix #5377 --------- Co-authored-by: Sam Xie <sam@samxie.me>
This commit is contained in:
Tyler Yahn
GitHub
parent
b00f496b93
commit
baa8efe132
@ -19,6 +19,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
|
||||
- Identify the `Tracer` returned from the global `TracerProvider` in `go.opentelemetry.io/otel/global` with its schema URL. (#5426)
|
||||
- Identify the `Meter` returned from the global `MeterProvider` in `go.opentelemetry.io/otel/global` with its schema URL. (#5426)
|
||||
- Log a warning to the OpenTelemetry internal logger when a `Span` in `go.opentelemetry.io/otel/sdk/trace` drops an attribute, event, or link due to a limit being reached. (#5434)
|
||||
- Document instrument name requirements in `go.opentelemetry.io/otel/metric`. (#5435)
|
||||
|
||||
## [1.27.0/0.49.0/0.3.0] 2024-05-21
|
||||
|
||||
|
||||
@ -57,6 +57,23 @@ asynchronous measurement, a Gauge ([Int64ObservableGauge] and
|
||||
See the [OpenTelemetry documentation] for more information about instruments
|
||||
and their intended use.
|
||||
|
||||
# Instrument Name
|
||||
|
||||
OpenTelemetry defines an [instrument name syntax] that restricts what
|
||||
instrument names are allowed.
|
||||
|
||||
Instrument names should ...
|
||||
|
||||
- Not be empty.
|
||||
- Have an alphabetic character as their first letter.
|
||||
- Have any letter after the first be an alphanumeric character, ‘_’, ‘.’,
|
||||
‘-’, or ‘/’.
|
||||
- Have a maximum length of 255 letters.
|
||||
|
||||
To ensure compatibility with observability platforms, all instruments created
|
||||
need to conform to this syntax. Not all implementations of the API will validate
|
||||
these names, it is the callers responsibility to ensure compliance.
|
||||
|
||||
# Measurements
|
||||
|
||||
Measurements are made by recording values and information about the values with
|
||||
@ -153,6 +170,7 @@ It is strongly recommended that authors only embed
|
||||
That implementation is the only one OpenTelemetry authors can guarantee will
|
||||
fully implement all the API interfaces when a user updates their API.
|
||||
|
||||
[instrument name syntax]: https://opentelemetry.io/docs/specs/otel/metrics/api/#instrument-name-syntax
|
||||
[OpenTelemetry documentation]: https://opentelemetry.io/docs/concepts/signals/metrics/
|
||||
[GetMeterProvider]: https://pkg.go.dev/go.opentelemetry.io/otel#GetMeterProvider
|
||||
*/
|
||||
|
||||
@ -47,20 +47,36 @@ type Meter interface {
|
||||
// Int64Counter returns a new Int64Counter instrument identified by name
|
||||
// and configured with options. The instrument is used to synchronously
|
||||
// record increasing int64 measurements during a computational operation.
|
||||
//
|
||||
// The name needs to conform to the OpenTelemetry instrument name syntax.
|
||||
// See the Instrument Name section of the package documentation for more
|
||||
// information.
|
||||
Int64Counter(name string, options ...Int64CounterOption) (Int64Counter, error)
|
||||
// Int64UpDownCounter returns a new Int64UpDownCounter instrument
|
||||
// identified by name and configured with options. The instrument is used
|
||||
// to synchronously record int64 measurements during a computational
|
||||
// operation.
|
||||
//
|
||||
// The name needs to conform to the OpenTelemetry instrument name syntax.
|
||||
// See the Instrument Name section of the package documentation for more
|
||||
// information.
|
||||
Int64UpDownCounter(name string, options ...Int64UpDownCounterOption) (Int64UpDownCounter, error)
|
||||
// Int64Histogram returns a new Int64Histogram instrument identified by
|
||||
// name and configured with options. The instrument is used to
|
||||
// synchronously record the distribution of int64 measurements during a
|
||||
// computational operation.
|
||||
//
|
||||
// The name needs to conform to the OpenTelemetry instrument name syntax.
|
||||
// See the Instrument Name section of the package documentation for more
|
||||
// information.
|
||||
Int64Histogram(name string, options ...Int64HistogramOption) (Int64Histogram, error)
|
||||
// Int64Gauge returns a new Int64Gauge instrument identified by name and
|
||||
// configured with options. The instrument is used to synchronously record
|
||||
// instantaneous int64 measurements during a computational operation.
|
||||
//
|
||||
// The name needs to conform to the OpenTelemetry instrument name syntax.
|
||||
// See the Instrument Name section of the package documentation for more
|
||||
// information.
|
||||
Int64Gauge(name string, options ...Int64GaugeOption) (Int64Gauge, error)
|
||||
// Int64ObservableCounter returns a new Int64ObservableCounter identified
|
||||
// by name and configured with options. The instrument is used to
|
||||
@ -71,6 +87,10 @@ type Meter interface {
|
||||
// the WithInt64Callback option to register the callback here, or use the
|
||||
// RegisterCallback method of this Meter to register one later. See the
|
||||
// Measurements section of the package documentation for more information.
|
||||
//
|
||||
// The name needs to conform to the OpenTelemetry instrument name syntax.
|
||||
// See the Instrument Name section of the package documentation for more
|
||||
// information.
|
||||
Int64ObservableCounter(name string, options ...Int64ObservableCounterOption) (Int64ObservableCounter, error)
|
||||
// Int64ObservableUpDownCounter returns a new Int64ObservableUpDownCounter
|
||||
// instrument identified by name and configured with options. The
|
||||
@ -81,6 +101,10 @@ type Meter interface {
|
||||
// the WithInt64Callback option to register the callback here, or use the
|
||||
// RegisterCallback method of this Meter to register one later. See the
|
||||
// Measurements section of the package documentation for more information.
|
||||
//
|
||||
// The name needs to conform to the OpenTelemetry instrument name syntax.
|
||||
// See the Instrument Name section of the package documentation for more
|
||||
// information.
|
||||
Int64ObservableUpDownCounter(name string, options ...Int64ObservableUpDownCounterOption) (Int64ObservableUpDownCounter, error)
|
||||
// Int64ObservableGauge returns a new Int64ObservableGauge instrument
|
||||
// identified by name and configured with options. The instrument is used
|
||||
@ -91,26 +115,46 @@ type Meter interface {
|
||||
// the WithInt64Callback option to register the callback here, or use the
|
||||
// RegisterCallback method of this Meter to register one later. See the
|
||||
// Measurements section of the package documentation for more information.
|
||||
//
|
||||
// The name needs to conform to the OpenTelemetry instrument name syntax.
|
||||
// See the Instrument Name section of the package documentation for more
|
||||
// information.
|
||||
Int64ObservableGauge(name string, options ...Int64ObservableGaugeOption) (Int64ObservableGauge, error)
|
||||
|
||||
// Float64Counter returns a new Float64Counter instrument identified by
|
||||
// name and configured with options. The instrument is used to
|
||||
// synchronously record increasing float64 measurements during a
|
||||
// computational operation.
|
||||
//
|
||||
// The name needs to conform to the OpenTelemetry instrument name syntax.
|
||||
// See the Instrument Name section of the package documentation for more
|
||||
// information.
|
||||
Float64Counter(name string, options ...Float64CounterOption) (Float64Counter, error)
|
||||
// Float64UpDownCounter returns a new Float64UpDownCounter instrument
|
||||
// identified by name and configured with options. The instrument is used
|
||||
// to synchronously record float64 measurements during a computational
|
||||
// operation.
|
||||
//
|
||||
// The name needs to conform to the OpenTelemetry instrument name syntax.
|
||||
// See the Instrument Name section of the package documentation for more
|
||||
// information.
|
||||
Float64UpDownCounter(name string, options ...Float64UpDownCounterOption) (Float64UpDownCounter, error)
|
||||
// Float64Histogram returns a new Float64Histogram instrument identified by
|
||||
// name and configured with options. The instrument is used to
|
||||
// synchronously record the distribution of float64 measurements during a
|
||||
// computational operation.
|
||||
//
|
||||
// The name needs to conform to the OpenTelemetry instrument name syntax.
|
||||
// See the Instrument Name section of the package documentation for more
|
||||
// information.
|
||||
Float64Histogram(name string, options ...Float64HistogramOption) (Float64Histogram, error)
|
||||
// Float64Gauge returns a new Float64Gauge instrument identified by name and
|
||||
// configured with options. The instrument is used to synchronously record
|
||||
// instantaneous float64 measurements during a computational operation.
|
||||
//
|
||||
// The name needs to conform to the OpenTelemetry instrument name syntax.
|
||||
// See the Instrument Name section of the package documentation for more
|
||||
// information.
|
||||
Float64Gauge(name string, options ...Float64GaugeOption) (Float64Gauge, error)
|
||||
// Float64ObservableCounter returns a new Float64ObservableCounter
|
||||
// instrument identified by name and configured with options. The
|
||||
@ -121,6 +165,10 @@ type Meter interface {
|
||||
// the WithFloat64Callback option to register the callback here, or use the
|
||||
// RegisterCallback method of this Meter to register one later. See the
|
||||
// Measurements section of the package documentation for more information.
|
||||
//
|
||||
// The name needs to conform to the OpenTelemetry instrument name syntax.
|
||||
// See the Instrument Name section of the package documentation for more
|
||||
// information.
|
||||
Float64ObservableCounter(name string, options ...Float64ObservableCounterOption) (Float64ObservableCounter, error)
|
||||
// Float64ObservableUpDownCounter returns a new
|
||||
// Float64ObservableUpDownCounter instrument identified by name and
|
||||
@ -131,6 +179,10 @@ type Meter interface {
|
||||
// the WithFloat64Callback option to register the callback here, or use the
|
||||
// RegisterCallback method of this Meter to register one later. See the
|
||||
// Measurements section of the package documentation for more information.
|
||||
//
|
||||
// The name needs to conform to the OpenTelemetry instrument name syntax.
|
||||
// See the Instrument Name section of the package documentation for more
|
||||
// information.
|
||||
Float64ObservableUpDownCounter(name string, options ...Float64ObservableUpDownCounterOption) (Float64ObservableUpDownCounter, error)
|
||||
// Float64ObservableGauge returns a new Float64ObservableGauge instrument
|
||||
// identified by name and configured with options. The instrument is used
|
||||
@ -141,6 +193,10 @@ type Meter interface {
|
||||
// the WithFloat64Callback option to register the callback here, or use the
|
||||
// RegisterCallback method of this Meter to register one later. See the
|
||||
// Measurements section of the package documentation for more information.
|
||||
//
|
||||
// The name needs to conform to the OpenTelemetry instrument name syntax.
|
||||
// See the Instrument Name section of the package documentation for more
|
||||
// information.
|
||||
Float64ObservableGauge(name string, options ...Float64ObservableGaugeOption) (Float64ObservableGauge, error)
|
||||
|
||||
// RegisterCallback registers f to be called during the collection of a
|
||||
|
||||
Loading…
Reference in New Issue
Block a user