From f3939613bfe61abd65723d5a5e0e8472e76a0608 Mon Sep 17 00:00:00 2001 From: k1chik Date: Mon, 4 May 2026 10:48:26 -0400 Subject: [PATCH 1/2] docs: clarify collect() generator usage and API Reference snippet context Add a note to the collect() protocol section explaining that yield is idiomatic (generator iterates lazily, no state between scrapes) and a preamble to the API Reference section clarifying that code snippets belong inside a collect() method. Follows up on review feedback in #1169. Signed-off-by: k1chik --- docs/content/collector/custom.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/content/collector/custom.md b/docs/content/collector/custom.md index 62c0180a..48d4bac6 100644 --- a/docs/content/collector/custom.md +++ b/docs/content/collector/custom.md @@ -47,6 +47,11 @@ can also implement `describe`. Returns an iterable of metric family objects (`GaugeMetricFamily`, `CounterMetricFamily`, etc.). Called every time the registry is scraped. +Using `yield` is the idiomatic way to implement `collect()` — it turns the method +into a generator, which the registry iterates lazily without building an intermediate +list first. Each scrape calls `collect()` fresh, so no state carries over between +scrapes. + ### `describe()` Returns an iterable of metric family objects used only to determine the metric @@ -76,6 +81,10 @@ g.add_metric(['eu-west-1'], 5) ## API Reference +The examples below show usage inside a `collect()` method body. Each snippet is +meant to be placed within a custom collector class as shown in the example at the +top of this page. + ### GaugeMetricFamily ```python From 363b74bd2dc33dd74ebe85747302a9f522c095c8 Mon Sep 17 00:00:00 2001 From: k1chik Date: Mon, 4 May 2026 10:51:39 -0400 Subject: [PATCH 2/2] docs: split InfoMetricFamily example into two separate blocks The single block with two yield statements looked like one collect() yielding both patterns. Split into labelled prose + code pairs to make clear they are alternatives, not sequential yields. Signed-off-by: k1chik --- docs/content/collector/custom.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/content/collector/custom.md b/docs/content/collector/custom.md index 48d4bac6..c1979109 100644 --- a/docs/content/collector/custom.md +++ b/docs/content/collector/custom.md @@ -241,11 +241,15 @@ InfoMetricFamily(name, documentation, value=None, labels=None) | `value` | `Dict[str, str]` | Key-value label pairs that form the info payload. | | `timestamp` | `float` or `Timestamp` | Optional Unix timestamp. | +Single unlabelled info metric: + ```python -# single unlabelled info metric yield InfoMetricFamily('build', 'Build metadata', value={'version': '1.2.3', 'commit': 'abc123'}) +``` -# labelled: one info metric per service +Labelled — one info metric per service: + +```python i = InfoMetricFamily('service_build', 'Per-service build info', labels=['service']) i.add_metric(['auth'], {'version': '2.0.1', 'commit': 'def456'}) i.add_metric(['api'], {'version': '1.9.0', 'commit': 'ghi789'})