Repository navigation
Give Meter an attribute dimension and a stability promise - #10
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Finding 1 of the pre-v1.0 API review.
Meteris the interface we are about to freeze, and it had two ceilings that could not be lifted after v1.0:PerWorkerbreakdown thatReportalready exposes (and the README already advertises) could never be streamed, because there is no way to label an instrument.Meter, which breaks every implementor.The design, and why
Attris 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)andHistogram.Record(time.Duration)stay exactly as they are.CounterVecwith label names known up front, and everyAddwould 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,CounterandHistogramwill not gain methods. New instrument kinds arrive as separate optional interfaces discovered by type assertion — thehttp.Flusherpattern — so aMeterwritten today keeps compiling and keeps working.Validated before freezing the shape
Both exporters were implemented against this API in a local
go.workand 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 pinnedflow v0.6.0(undefined: flow.Attr), so they follow once this is tagged.Verification
go vet+go build+go test -race -count=1green on core and over thex/*/submodule loop.Breaking change
Breaking for
Meterimplementors (the signature gained a variadic parameter) — which is exactly who had to break before v1.0. Callers are unaffected. Suggests av0.7.0tag.🤖 Generated with Claude Code
https://claude.ai/code/session_01LGsdwoFd3a7bejBXLr6saG