Verify compliant metric API specification implementation: Instrument Histogram

[MrAlias]

• Identify all the normative requirements, recommendations, and options the specification defines as comments to this issue
• Ensure the current metric API implementation is compliant with these normative requirements, recommendations, and options in those comments.

[MrAlias]

#3454

[MrAlias]

There MUST NOT be any API for creating a Histogram other than with a Meter.

Post #3454, our implementation is compliant with this.

[MrAlias]

This MAY be called CreateHistogram. If strong type is desired, OpenTelemetry API authors MAY decide the language idiomatic name(s), for example CreateUInt64Histogram, CreateDoubleHistogram, CreateHistogram<UInt64>, CreateHistogram<double>.

We do not follow this optional criteria. We instead follow more common Go method naming and use Int64Histogram and Float64Histogram.

[MrAlias]

This API SHOULD NOT return a value (it MAY return a dummy value if required by certain programming languages or systems, for example null, undefined).

Our implementations do not return a value:

opentelemetry-go/metric/instrument/syncfloat64/syncfloat64.go

Line 49 in efd8a7d

Record(ctx context.Context, incr float64, attrs ...attribute.KeyValue)

opentelemetry-go/metric/instrument/syncint64/syncint64.go

Line 49 in efd8a7d

Record(ctx context.Context, incr int64, attrs ...attribute.KeyValue)

[MrAlias]

Parameters:

• The amount of the Measurement, which MUST be a non-negative numeric value.
• Optional attributes.

These parameters are define non-normatively (though I suspect they are meant to be, see open-telemetry/opentelemetry-specification#3082).

Both parameters are accepted for the Add methods of counters:

opentelemetry-go/metric/instrument/syncfloat64/syncfloat64.go

Line 49 in efd8a7d

Record(ctx context.Context, incr float64, attrs ...attribute.KeyValue)

opentelemetry-go/metric/instrument/syncint64/syncint64.go

Line 49 in efd8a7d

Record(ctx context.Context, incr int64, attrs ...attribute.KeyValue)

The amount of the Measurement, which MUST be a non-negative numeric value.

Again, if the Measurment needs to be guaranteed by the API or not to be non-negative is still an open question: open-telemetry/opentelemetry-specification#3081

[MrAlias]

The OpenTelemetry API authors MAY decide to allow flexible attributes to be passed in as arguments. If the attribute names and types are provided during the counter creation, the OpenTelemetry API authors MAY allow attribute values to be passed in using a more efficient way (e.g. strong typed struct allocated on the callstack, tuple). The API MUST allow callers to provide flexible attributes at invocation time rather than having to register all the possible attribute names during the instrument creation.

We do not allow attribute name/type registration at instrument creation time, meaning we do not support this optional feature. We do comply with the requirement to allow users to provide flexible attributes at invocation (of the Add API) time.

[MrAlias]

Remaining:

• Open question: Are metric APIs expected to restrict counter input values? opentelemetry-specification#3081

[MrAlias]

Resolved by open-telemetry/opentelemetry-specification#3082