From b21efd2a4839acebc3371e240c96446c80c457ee Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Tue, 5 May 2026 16:14:12 +0000 Subject: [PATCH 1/2] docs: clarify downstream adapter validation requirements Signed-off-by: Gregor Zeitlinger --- docs/content/getting-started/registry.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/content/getting-started/registry.md b/docs/content/getting-started/registry.md index 45383d72a..f50c8fe4f 100644 --- a/docs/content/getting-started/registry.md +++ b/docs/content/getting-started/registry.md @@ -116,6 +116,14 @@ and full label-schema validation and duplicate detection still apply. A collecto non-null type but leaves `getLabelNames()` as `null` is still validated, with its labels treated as empty. +This is also relevant for downstream adapter libraries that bridge to this registry. If an adapter +implements `MultiCollector`, its registration-time metadata must match the metric families it will +actually emit at scrape time. In practice, that means `getPrometheusNames()`, `getMetricType(...)`, +`getLabelNames(...)`, and `getMetadata(...)` need to describe the same names, types, labels, and +suffix behavior as the eventual `MetricSnapshot` output. Otherwise an adapter may pass or fail +collision checks differently after upgrading to a newer client_java release, even if its scrape +output logic did not change. + ## Unregistering a Metric There is no automatic expiry of unused metrics (yet), once a metric is registered it will remain From 5052dbfd6dee134847d33ae053283af376178e24 Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Tue, 5 May 2026 16:16:41 +0000 Subject: [PATCH 2/2] docs: document downstream adapter validation guidance Signed-off-by: Gregor Zeitlinger --- CHANGELOG.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 72012dcc8..7daa57cd4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,12 @@ > To keep the Prometheus and OM1 output unambiguous, the registry tracks claimed exposition names > and still rejects registrations that would collide at scrape time. > +> Downstream adapter libraries that implement `MultiCollector` need their registration-time +> metadata to match the metric families they emit at scrape time. When upgrading to 1.6.0+, adapter +> registration metadata needs to stay aligned with emitted names, types, label names, and suffix +> behavior under the new collision model. +> See also: [Validation at registration only](docs/content/getting-started/registry.md#validation-at-registration-only) +> > | Example | Before 1.6.0 | Since 1.6.0 | Reason | > | --- | --- | --- | --- | > | `Gauge("foo_total")` | Rejected | Allowed | Not breaking because this previously failed at registration, so no working setup changes behavior, and safe because `_total` suffix expansion applies to counters, not gauges. |