Verify compliant metric API specification implementation: Instrument UpDownCounter

[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 an UpDownCounter other than with a Meter.

Post #3454, our implementation is compliant with this.

[MrAlias]

This MAY be called CreateUpDownCounter. If strong type is desired, OpenTelemetry API authors MAY decide the language idiomatic name(s), for example CreateInt64UpDownCounter, CreateDoubleUpDownCounter, CreateUpDownCounter<Int64>, CreateUpDownCounter<double>.

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

[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).

We comply with this recommendation:

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

Line 39 in efd8a7d

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

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

Line 39 in 75a19d1

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

[MrAlias]

Parameters:

• The amount to be added, can be positive, negative or zero.
• Optional attributes.

I'm assuming these were meant to be normatively declared¹.

Both parameters are accepted for the Add methods of up-down counters:

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

Line 39 in efd8a7d

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

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

Line 39 in 75a19d1

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

Footnotes

1. https://github.com/open-telemetry/opentelemetry-specification/pull/3082 ↩

[MrAlias]

OpenTelemetry API authors MAY decide to allow flexible attributes to be passed in as individual arguments. 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).

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]

Every normative clause from the UpDownCounter section of the v1.16.0 specification has been identified and our API has been validated that it complies. Closing.