diff --git a/CHANGELOG.md b/CHANGELOG.md index a6c0888de73..411cfefd469 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,8 @@ 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):