From ccb33be6f30cf8b86fc32536467bbdc14d649402 Mon Sep 17 00:00:00 2001 From: Maxime Grenu Date: Thu, 19 Feb 2026 10:56:14 +0100 Subject: [PATCH 1/2] api: add docstrings to core metrics instrument abstract methods MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add missing docstrings to the abstract measurement methods on the four core synchronous metric instruments: - Counter.add – records a non-negative increment - UpDownCounter.add – records a positive or negative delta - Histogram.record – records an arbitrary statistical measurement - Gauge.set – records the current (non-additive) value Each docstring explains the intent of the method, any constraints on the parameter, and documents all three parameters (amount, attributes, context) using the existing Google-style format already present in the codebase. These methods are the primary interaction surface for developers using the OpenTelemetry Metrics API; having no docstring on the abstract definition makes generated API docs and IDE tooltips silent. --- CHANGELOG.md | 3 ++ .../metrics/_internal/instrument.py | 50 +++++++++++++++++-- 2 files changed, 49 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a6c0888de73..4ff6269299b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased +- `opentelemetry-api`: Add docstrings to `Counter.add`, `UpDownCounter.add`, `Histogram.record`, and `Gauge.set` abstract methods + ([#4923](https://github.com/open-telemetry/opentelemetry-python/pull/4923)) + - `opentelemetry-sdk`: Clarify timeout units in environment variable documentation ([#4906](https://github.com/open-telemetry/opentelemetry-python/pull/4906)) - `opentelemetry-exporter-otlp-proto-grpc`: Fix re-initialization of gRPC channel on UNAVAILABLE error diff --git a/opentelemetry-api/src/opentelemetry/metrics/_internal/instrument.py b/opentelemetry-api/src/opentelemetry/metrics/_internal/instrument.py index 0d5ec951074..cfd7a1526c6 100644 --- a/opentelemetry-api/src/opentelemetry/metrics/_internal/instrument.py +++ b/opentelemetry-api/src/opentelemetry/metrics/_internal/instrument.py @@ -183,7 +183,14 @@ def add( attributes: Optional[Attributes] = None, context: Optional[Context] = None, ) -> None: - pass + """Records an increment to the counter. + + Args: + amount: The amount to increment the counter by. Must be non-negative. + attributes: Optional set of attributes to associate with the measurement. + context: Optional context to associate with the measurement. If not + provided, the current context is used. + """ class NoOpCounter(Counter): @@ -234,7 +241,18 @@ def add( attributes: Optional[Attributes] = None, context: Optional[Context] = None, ) -> None: - pass + """Records an increment or decrement to the counter. + + Unlike `Counter`, the ``amount`` may be negative, allowing the + instrument to track values that go up and down (e.g. number of + active requests, queue depth). + + Args: + amount: The amount to add to the counter. May be positive or negative. + attributes: Optional set of attributes to associate with the measurement. + context: Optional context to associate with the measurement. If not + provided, the current context is used. + """ class NoOpUpDownCounter(UpDownCounter): @@ -376,7 +394,20 @@ def record( attributes: Optional[Attributes] = None, context: Optional[Context] = None, ) -> None: - pass + """Records a measurement. + + Used to report measurements that are likely to be statistically + meaningful, such as request durations, payload sizes, or any value + for which a distribution (e.g. percentiles) is useful. + + Args: + amount: The measurement to record. Should be non-negative in most + cases; negative values are only meaningful when the histogram + is used to track signed deltas. + attributes: Optional set of attributes to associate with the measurement. + context: Optional context to associate with the measurement. If not + provided, the current context is used. + """ class NoOpHistogram(Histogram): @@ -486,7 +517,18 @@ def set( attributes: Optional[Attributes] = None, context: Optional[Context] = None, ) -> None: - pass + """Records the current value of the gauge. + + The gauge reports the last recorded value when observed. It is + intended for non-additive measurements where only the current + value matters (e.g. CPU utilisation percentage, room temperature). + + Args: + amount: The current value to record. + attributes: Optional set of attributes to associate with the measurement. + context: Optional context to associate with the measurement. If not + provided, the current context is used. + """ class NoOpGauge(Gauge): From f4b0d1f68e9e8a3308ff77c095d9540b4b852831 Mon Sep 17 00:00:00 2001 From: Riccardo Magliocchetti Date: Thu, 19 Feb 2026 16:47:22 +0100 Subject: [PATCH 2/2] Apply suggestion from @xrmx --- CHANGELOG.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4ff6269299b..411cfefd469 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `opentelemetry-api`: Add docstrings to `Counter.add`, `UpDownCounter.add`, `Histogram.record`, and `Gauge.set` abstract methods ([#4923](https://github.com/open-telemetry/opentelemetry-python/pull/4923)) - - `opentelemetry-sdk`: Clarify timeout units in environment variable documentation ([#4906](https://github.com/open-telemetry/opentelemetry-python/pull/4906)) - `opentelemetry-exporter-otlp-proto-grpc`: Fix re-initialization of gRPC channel on UNAVAILABLE error