Definition of instrumentation types (counter & up down counter) needs correction

[thompson-tomo]

What needs to be changed?

The definition of the counter & up down counter instrumentation types needs to be corrected as counters can apparently also go down ie Reset. This means that the example should also be updated.

What is the name + path of the page that needs changed?

https://opentelemetry.io/docs/concepts/signals/metrics/#metric-instruments

Additional context: anything else you can think about that would be helpful.

open-telemetry/semantic-conventions#2996 (comment)

_{Tip:
React
with 👍 to help prioritize this issue. Please use comments to provide useful
context, avoiding +1 or me too, to help us triage it. Learn more
here.}

[jsuereth]

This isn't a real issue. A counter reset is expected with the lifetime of the resource expires. Metric systems are designed to handle this, e.g. the Rate function in prometheus:

Breaks in monotonicity (such as counter resets due to target restarts) are automatically adjusted for.

If a counter is reset when the resource resets or if it overflows due to bounds on size of long, that is expected and handled.

I'm closing this as currently phrased.

cc @jmacd for thoughts on whether we need to expand metric specification to better explain counter usage in practice. I think we took it for granted people understood that resets are allowed when a resource identity changes.

[thompson-tomo]

@jsuereth this is in relation to the concepts page which explicitly states that it only ever goes up.

Counter: A value that accumulates over time – you can think of this like an odometer on a car; it only ever goes up.

[jsuereth]

It only ever goes up - For the lifetime of the resource. That's implicit and described in the metric data model. It can only ever go up for when start-time -> end time exists for the metric point. A process restart causing a start time restart means it's technically a new timeseries (or a counter reset) and metric systems are designed to handle that. In fact, we want this.

The UpDownCounter is when a value can go up or down for the same resource (or within the start/stop time boundary). That cannot use "rate" calculations in metric storage, so that's the primary distinction here.

[thompson-tomo]

I have no problem with the restart nature, just that should be explicitly called out in the concept page.

Even changing

Counter: A value that accumulates over time – you can think of this like an odometer on a car; it only ever goes up.

To

Counter: A value that accumulates over time – you can think of this like an odometer on a car during a drive; it only ever goes up but could be reset when the car stops.

Would be an improvement.

[thompson-tomo]

Or even better:

Counter: A value that accumulates over time – you can think of this like a car trip computer; it only ever goes up until a reset is triggered at which point it starts again from 0.