Remove the Metric Gauge instrument, recommend use of other instruments

[jmacd]

This was discussed in the 1/16 Metrics SIG meeting. This was first filed as open-telemetry/opentelemetry-specification#412

[yurishkuro]

The reduction of API surface in this change is counterbalanced by requiring more work from the user, which makes migration to OTel more difficult. I would not be in favor of removing support for sync calls.

However, I notice that you're not extending the argument to Measure instrument. As discussed offline, I'm not clear on the difference between Measure and Gauge, and I would actually prefer to see Measure removed as more ambiguous. Gauge simply captures an observation as raw number. Traditional last-write-wins behavior can be an aggregation option.

[jmacd]

@yurishkuro Thank you. I rewrote large parts of this document to address some of the points you raised. I have tried to argue that one of the other three instrument kinds is always appropriate.

If I understand your position on Gauge vs. Measure, I think it's overly reductive to say that Measure could be replaced by Gauge, but I agree that Gauge can be replaced by measure in some cases and that there's not an additional burden for migration in all but the rarest cases. These rare cases are cases where Observer instruments are truly the right choice and Counter and Measure would not apply, but that the performance impact of a callback approach is not acceptable.

In the new text, I've tried to clarify the distinction between Observer and the other kinds of instrument, that of there being a "current set of measured values" across multiple label sets without reference to an interval of time.

[c24t]

LGTM, and the examples are very helpful.

[jmacd]

I can still be convinced not to go with this proposal, but I'm definitely leaning towards it now. Thinking about how to implement the Gauge Set helper introduced as a mitigation strategy, it occurs to me that a special instance of the default SDK could be configured to support the Gauge Set by translating Gauge.Set to Measure.Record in the special-purpose SDK. An Observer instrument would be registered to export the contents of the special-purpose SDK via observations. I.e., When the observer callback is called, the set of last-values is collected from the underlying Measure instruments of the special-purpose SDK.

[tsloughter]

I would actually prefer to see Measure removed as more ambiguous.

Measure is absolutely needed. Measure, through attaching aggregations, can cover Counter and Gauge, but not the other way around.

I still see Counter and Gauge (Observable or not) as optimizations, which I like. OpenCensus there was only record and aggregation done in views. If you have something that is for sure for counting, or observing as a gauge, having these as high level concepts helps with both readability and optimizing the code path, doing the aggregation in-process.

But I'm +1 on removing the Gauge instrument. Easy to add it it back if needed.

[MrAlias]

This OTEP does a good job highlighting why it is advantageous to remove gauges from the developer perspective. However, one of the things that is really important in building out an API is to consider the user of the API and the APIs lifecycle. As @bogdandrutu pointed out in open-telemetry/opentelemetry-specification#412:

Apply the rule of minimal API surface: because there are some unknowns with the Gauge implementation and because we don't have very good use-cases for these type of instruments it is better to avoid adding them in the API for the moment. In case of a clear use-case determined later we should re-evaluate if adding the Gauge instrument back is the right decision or we do have different other solutions.

I think this is an understated point, but one that should be central to this discussion. Including Gauges in the API to only later in the lifecycle determine their meaning needs to change (how they support complex aggregations), or they need to be removed, is a bad design decision and one that will reflect poorly on the OpenTelemetry project overall.

@yurishkuro does bring up a valid point in questioning whether the lack of Gauges would result in a loss of functionality to the final user, but I think @jmacd and @tsloughter are correct in providing reasons as to why this is not the case.

I'm in favor of removing the Gauge from the API if we cannot come up with any valid use-cases for them. @jmacd do you think adding a bit about the API design choice to the motivation a needed part of the OTEP?

[yurishkuro]

Love the examples, I think they are sorely missing in general in the Spec for metrics.

[bogdandrutu]

@open-telemetry/specs-approvers please review, we need couple more reviews to merge this