On this page
Write the counter contract before inspecting drops
The source dates shown in this guide identify documentation checks on 22 October 2026, not original publication dates. Record metric name, unit, monotonic flag, aggregation temporality, expected writer identity, numeric width, and collection interval. A business total, process-local counter, and device register can all be called a count while having different reset and wrap rules. If the producer contract is unavailable, mark the cause unknown rather than inventing a restart policy.
| Field | Record | Why it matters |
|---|---|---|
| Metric identity | Name, resource, scope, attributes | Separates streams that look alike |
| Temporality | Cumulative or delta | Defines what each value covers |
| Start time | Exact field or unavailable | Can reveal a new sequence |
| Writer | Process, device, or unknown | Overlapping writers can mimic resets |
| Width | Declared integer width or unknown | Wraparound depends on representation |
| Collection | Expected interval and loss notes | A gap is not a zero |
Do not infer a reset only from a lower value. First compare identity and timestamps. A changed resource label may be a new stream, while an unchanged label from two writers may create an overlap that looks like a reset.
Classify a drop with four competing explanations
Use a finding row for each decrease. A restart reset often has a new start time or a zero-like beginning, but the evidence may be unavailable. A wraparound occurs when a bounded representation returns to a low value after its maximum, and requires width and producer semantics. An overlap may show two writers or conflicting intervals. A lost sample can make a valid sequence appear to jump without exposing the cause.
| Hypothesis | Evidence to seek | Do not claim |
|---|---|---|
| Restart reset | New process or start timestamp, low first value | Every drop was a restart |
| Wraparound | Known width, maximum, and rollover convention | A low value proves rollover |
| Overlap | Writer identity and interval intersection | Duplicate values are harmless |
| Lost data | Gap in timestamps or collector status | Interpolated count is observed |
| Bad instrument | Contract violation or impossible sequence | Rate is meaningful without repair |
The OpenTelemetry, (opens in a new tab) specification treats a gap, a reset, and overlapping writers as separate stream conditions. Preserve those categories even when the final dashboard groups them under one warning.
Calculate rates only after sequence boundaries are marked
For a cumulative counter, segment the series at each supported reset boundary. Within a segment, retain the original values and timestamps, then record the chosen rate window and handling for late or missing points. For a delta stream, record interval start and end and check for overlaps before summing. If a reset cause is unknown, publish the segment boundary and an uncertainty note rather than silently adding an offset.
- Sort by timestamp only after preserving the source order and sequence number.
- Group by the complete metric identity and expected writer.
- Mark decreases, timestamp gaps, overlaps, and missing start fields.
- Split the stream at supported reset boundaries.
- Compute a derived rate with its window, unit, and excluded intervals.
- Keep the raw sequence beside every derived value.
Use a synthetic sequence to test the worksheet
Synthetic counter findings
stream=fixture.requests; width=8-bit; temporality=cumulative
time | value | writer | start | finding
00:00Z | 250 | A | 00:00Z | baseline
00:10Z | 254 | A | 00:00Z | increase
00:20Z | 2 | A | 00:20Z | reset-or-wrap
00:30Z | 5 | B | unknown | writer-change
00:40Z | 8 | A | 00:20Z | overlap-check
review: do not compute one continuous rate until each finding is resolved| Fixture test | Expected worksheet result | Hold condition |
|---|---|---|
| Reset candidate | New start time recorded | Reset assumed from value only |
| Wrap candidate | Width and maximum requested | Width missing |
| Writer change | A and B treated as separate identities | Labels merged |
| Overlap | Intervals compared before summing | Rows deduplicated silently |
| Missing point | Gap flagged as unknown contribution | Gap filled as zero |
This fixture is intentionally synthetic and has no operational meaning. Add a reset with no start timestamp, a delta interval that overlaps its predecessor, and a missing middle point. The worksheet should emit a stable finding class and a next evidence request for each case.
Keep telemetry findings separate from performance conclusions
Counter review can document sequence behavior and the limits of a derived rate. It cannot establish service performance, incident cause, device health, or fitness for a downstream use. Preserve the metric identity, raw points, stream boundaries, and collection notes so an owner can make those decisions with the right context.
Pair this guide with event ordering and replay review for sequence evidence and export timestamps and timezones for clock context. After a supported non-health scope, authority to describe the collection, and a controlled telemetry packet are established, the qualified appraisal request path may be a preparation step. It does not read metrics, repair counters, create a quote, match a buyer, or grant a license.
Takeaways
- Define counter identity, temporality, width, writer, and timestamp fields first.
- Treat reset, wraparound, overlap, loss, and instrument error as separate hypotheses.
- Segment streams before deriving rates and keep corrections as new artifacts.
- Use synthetic sequences to exercise unknown starts and missing samples.
- Do not turn a lower value into a causal story without producer evidence.