docs(metrics): note the two-seam overlap hazard in the truth-home#146
Merged
Conversation
architecture/metrics.md §Two-seam layering framed the recorder and native middleware as purely complementary, omitting that they overlap on the consume/publish series: both emit the same-named duration+count metrics, so one Prometheus registry raises Duplicated timeseries and live OTel meters on both double-count. Record the hazard, the separate-registries / middleware-as-source- of-truth fix, and why the library does not guard it at construction (the collision is raised upstream of the broker, and "both seams configured" is indistinguishable from the correct dual-registry setup). Cross-refs the setup doc, which already covers the operator side. Closes the last open item from the architecture review (candidate #7). Docs only. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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
1 participant
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.
What
Closes the last open item from the architecture review (candidate #7), as a docs-only change after research showed a code guard is infeasible.
Finding: the two observability seams (the
MetricsRecorderrecorder adapters and the native FastStream middleware) are complementary on bus-invisible events but overlap on the consume/publish series — both emit the same-named duration+count metrics. One PrometheusCollectorRegistryshared across both raisesDuplicated timeseries; live OTel meters on both double-count every consume/publish.Why no code guard: the Prometheus collision is raised at whichever seam the user constructs second — upstream of the broker, so the broker can't intercept it. And the only broker-detectable signal ("both seams configured") is indistinguishable from the correct dual-registry setup, so a construction-time guard would false-positive on the recommended configuration.
The user-facing setup doc (
docs/usage/setup-prometheus-opentelemetry.md) already covers the operator side. The only gap was the truth-home:architecture/metrics.md§Two-seam layering framed the seams as purely complementary and omitted the overlap. This adds the hazard, the separate-registries / middleware-as-source-of-truth fix, and the rationale for not guarding it in code.Docs only — no code, no tests.
🤖 Generated with Claude Code