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. | 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