From 73b2005d20d67a415e4934245b8cad293506dcfa Mon Sep 17 00:00:00 2001 From: Paul Calnon Date: Wed, 6 May 2026 08:39:54 -0500 Subject: [PATCH] docs(observability): cross-reference register_or_reuse helpers (Phase 3) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a brief "Observability — Prometheus Collectors" section to AGENTS.md pointing newcomers at the canonical helpers in juniper-observability >= 0.2.0 (``register_or_reuse`` / ``register_fresh`` / ``register_info_or_update`` / ``lazy_register_or_reuse``) plus the ``juniper_observability.testing.reset_prometheus_registry`` pytest fixture. Closes Phase 3 of the migration plan in ``juniper-ml/notes/observability/REGISTER_OR_REUSE_HELPER_DESIGN_2026-05-05.md``. Documentation only; no code changes. Co-Authored-By: Claude Opus 4.7 (1M context) --- AGENTS.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 20217ed..b1ab2ce 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -203,6 +203,19 @@ juniper-data/ --- +## Observability — Prometheus Collectors + +For any new `prometheus_client` `Counter` / `Gauge` / `Histogram` / `Summary` / `Info` / `Enum` registration, use the canonical helpers from `juniper-observability` (`>=0.2.0`): + +- `register_or_reuse(factory, name, *args, **kwargs)` — adopt-existing on duplicate (the default for almost every call site; preserves accumulated samples across in-process re-init). +- `register_fresh(...)` — drop-and-recreate on duplicate (only when args genuinely differ). +- `register_info_or_update(name, description, **labels)` — sugar for the `Info` two-step register-then-`.info({...})` pattern. +- `lazy_register_or_reuse(...)` — for the lazy-init-with-`None`-sentinel pattern. + +Tests touching these collectors should use `juniper_observability.testing.reset_prometheus_registry`. Existing examples in this repo: `juniper_data/api/observability.py:_ensure_dataset_metrics`. See [the design doc in juniper-ml](https://github.com/pcalnon/juniper-ml/blob/main/notes/observability/REGISTER_OR_REUSE_HELPER_DESIGN_2026-05-05.md) for the rationale. + +--- + ## Code Style Conventions ### Naming Conventions