TC Review Request: Go Metric API

[MrAlias]

The Go SIG is looking to make a stable release of the OpenTelemetry metric API in Go. We are looking for a TC member familiar with the metric API specification to review our offering and help ensure our compliance with the specification.

We are still working to ensure the compliance of the metric SDK. Therefore, this request is only scoped to the API.

Prior work

We have conducted our own internal review of the specification here. That review identified one outstanding compliance issue remains:

• Log a warning for duplicate instrument creation from the No-op Meter opentelemetry-go#3565

However, we believe this to be an specification issue. open-telemetry/opentelemetry-specification#3171 is opened to address this at the specification level.

Inventory

We would like to evaluate the v1.12.0/v0.35.0 Release, links should be related to this tag.

• Metric API package: https://github.com/open-telemetry/opentelemetry-go/tree/6cb5718eaaed5c408c3bf4ad1aecee5c20ccdaa9/metric
  • MeterProvider
  • Meter
  • Asynchronous instruments:
    • https://github.com/open-telemetry/opentelemetry-go/blob/6cb5718eaaed5c408c3bf4ad1aecee5c20ccdaa9/metric/instrument/asyncfloat64.go#L35-L56
    • https://github.com/open-telemetry/opentelemetry-go/blob/6cb5718eaaed5c408c3bf4ad1aecee5c20ccdaa9/metric/instrument/asyncint64.go#L35-L56
  • Single-instrument callbacks:
    • https://github.com/open-telemetry/opentelemetry-go/blob/6cb5718eaaed5c408c3bf4ad1aecee5c20ccdaa9/metric/instrument/asyncfloat64.go#L58-L79, https://github.com/open-telemetry/opentelemetry-go/blob/6cb5718eaaed5c408c3bf4ad1aecee5c20ccdaa9/metric/instrument/asyncfloat64.go#L125-L131
    • https://github.com/open-telemetry/opentelemetry-go/blob/6cb5718eaaed5c408c3bf4ad1aecee5c20ccdaa9/metric/instrument/asyncint64.go#L58-L79, https://github.com/open-telemetry/opentelemetry-go/blob/6cb5718eaaed5c408c3bf4ad1aecee5c20ccdaa9/metric/instrument/asyncint64.go#L125-L131
  • Multi-instrument callbacks:
    • https://github.com/open-telemetry/opentelemetry-go/blob/6cb5718eaaed5c408c3bf4ad1aecee5c20ccdaa9/metric/meter.go#L104-L129
  • Synchronous instruments:
    • https://github.com/open-telemetry/opentelemetry-go/blob/6cb5718eaaed5c408c3bf4ad1aecee5c20ccdaa9/metric/instrument/syncfloat64.go#L24-L54
    • https://github.com/open-telemetry/opentelemetry-go/blob/6cb5718eaaed5c408c3bf4ad1aecee5c20ccdaa9/metric/instrument/syncint64.go#L24-L54
• No-op implementation: https://github.com/open-telemetry/opentelemetry-go/blob/6cb5718eaaed5c408c3bf4ad1aecee5c20ccdaa9/metric/noop.go
• Metric portion of global API: https://github.com/open-telemetry/opentelemetry-go/tree/6cb5718eaaed5c408c3bf4ad1aecee5c20ccdaa9/metric/global

[reyang]

I can probably take it if it's okay to wait till mid Feb (13th-17th), please let me know if it is okay.

[MrAlias]

I can probably take it if it's okay to wait till mid Feb (13th-17th), please let me know if it is okay.

Yeah, that timeline works. Thanks 👍

[reyang]

I've scanned through all the links provided in the PR description and confirmed that they are compliant to the API specification.
I've also confirmed that the API spec has been well covered by the OTel Go API package, except for the following section (which is okay since we're targeting 1.12):

https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#get-a-meter

[since 1.13.0] attributes: Specifies the instrumentation scope attributes to associate with emitted telemetry.

Users can provide attributes to associate with the instrumentation scope, but it is up to their discretion. Therefore, this API MUST be structured to accept a variable number of attributes, including none.

One minor thing I've noticed:

https://github.com/open-telemetry/opentelemetry-go/blob/6cb5718eaaed5c408c3bf4ad1aecee5c20ccdaa9/trace/trace.go#L550 we seem to use name as the parameter for a provider to get a Tracer, https://github.com/open-telemetry/opentelemetry-go/blob/6cb5718eaaed5c408c3bf4ad1aecee5c20ccdaa9/metric/meter.go#L34 we use instrumentationName which is not very consistent with trace as well as the spec https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#get-a-meter.

[reyang]

@MrAlias I'm closing this issue as completed.

[jmacd]

I completely support the Go metrics API.
For the record, I maintain an alternate Go metrics SDK and have completed upgrading my code to use the new APIs. I found no difficulties and am pleased with the new APIs. lightstep/otel-launcher-go#381

[MrAlias]

One minor thing I've noticed:

https://github.com/open-telemetry/opentelemetry-go/blob/6cb5718eaaed5c408c3bf4ad1aecee5c20ccdaa9/trace/trace.go#L550 we seem to use name as the parameter for a provider to get a Tracer, https://github.com/open-telemetry/opentelemetry-go/blob/6cb5718eaaed5c408c3bf4ad1aecee5c20ccdaa9/metric/meter.go#L34 we use instrumentationName which is not very consistent with trace as well as the spec https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#get-a-meter.

Addressed by open-telemetry/opentelemetry-go#3734

[MrAlias]

I've scanned through all the links provided in the PR description and confirmed that they are compliant to the API specification. I've also confirmed that the API spec has been well covered by the OTel Go API package, except for the following section (which is okay since we're targeting 1.12):

https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#get-a-meter

[since 1.13.0] attributes: Specifies the instrumentation scope attributes to associate with emitted telemetry.
Users can provide attributes to associate with the instrumentation scope, but it is up to their discretion. Therefore, this API MUST be structured to accept a variable number of attributes, including none.

Addressing this with open-telemetry/opentelemetry-go#3738