8000 Give Meter an attribute dimension and a stability promise by pabloos · Pull Request #10 · pabloos/flow · GitHub
[go: up one dir, main page]

Skip to content

Give Meter an attribute dimension and a stability promise - #10

Merged
pabloos merged 1 commit into
mainfrom
feat/meter-attrs
Nov 1, 2026
Merged

pabloos merged 1 commit into
mainfrom
feat/meter-attrs

Conversation

@pabloos
@pabloos pabloos commented Nov 1, 2026
Copy link
Copy Markdown
Owner

Finding 1 of the pre-v1.0 API review. Meter is the interface we are about to freeze, and it had two ceilings that could not be lifted after v1.0:

  1. No attribute dimension — the PerWorker breakdown that Report already exposes (and the README already advertises) could never be streamed, because there is no way to label an instrument.
  2. No growth path — adding an instrument kind (a gauge for in-flight items, say) means adding a method to Meter, which breaks every implementor.

The design, and why

Attr is passed at instrument creation, not per measurement. flow's attributes are static per instrument — a worker index, a stage name — they never vary measurement to measurement. So:

  • Counter.Add(int64) and Histogram.Record(time.Duration) stay exactly as they are.
  • Exporters bake the attrs in once: Prometheus const labels, a precomputed OpenTelemetry attribute set. The recording path stays allocation-free.
  • Record-time attrs would have done the opposite: natural for OTel, but Prometheus would need a CounterVec with label names known up front, and every Add would allocate.

Variadic, so the engine's call sites are unchanged. The engine still asks for pipeline-wide aggregates with no attrs — pinned by TestEngineAsksForAggregateInstrumentsWithoutAttrs, so a stray attr (which would split a series and violate Prometheus' stable-label-dimension rule) fails loudly.

The growth path is now documented rather than left to chance: Meter, Counter and Histogram will not gain methods. New instrument kinds arrive as separate optional interfaces discovered by type assertion — the http.Flusher pattern — so a Meter written today keeps compiling and keeps working.

Validated before freezing the shape

Both exporters were implemented against this API in a local go.work and tested: attrs reach Prometheus as separate labelled series ({worker=0: 5, worker=1: 7}) and OTel as separate attributed data points. The exporter changes are not in this PR — they cannot compile against the pinned flow v0.6.0 (undefined: flow.Attr), so they follow once this is tagged.

Verification

go vet + go build + go test -race -count=1 green on core and over the x/*/ submodule loop.

Breaking change

Breaking for Meter implementors (the signature gained a variadic parameter) — which is exactly who had to break before v1.0. Callers are unaffected. Suggests a v0.7.0 tag.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LGsdwoFd3a7bejBXLr6saG

Meter was about to be frozen at v1.0 with two ceilings: no way to label an
instrument, so the PerWorker breakdown Report already exposes could never be
streamed; and no way to add an instrument kind without breaking every
implementor.

Add Attr, passed at instrument creation rather than per measurement, because
flow's attributes are static per instrument (worker index, stage name). That
keeps Add/Record untouched and lets exporters bake the attrs in once:
Prometheus const labels, a precomputed OpenTelemetry attribute set. Variadic,
so the engine's call sites are unchanged — it still asks for pipeline-wide
aggregates with no attrs, pinned by a test.

Document the growth path instead of leaving it to chance: Meter, Counter and
Histogram will not gain methods; new instrument kinds arrive as optional
interfaces found by type assertion (the http.Flusher pattern).

Validated against both exporters in a local go.work before freezing the shape:
attrs reach Prometheus as separate labelled series and OTel as separate
attributed data points. Those changes land once this is tagged, since they
cannot compile against the currently pinned flow v0.6.0.
@pabloos
pabloos merged commit c64143d into main Nov 1, 2026
2 checks passed
@pabloos
pabloos deleted the feat/meter-attrs branch November 1, 2026 19:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

0