From faf8868f7a3d7f64ea3214cf6f201bb95d8ec513 Mon Sep 17 00:00:00 2001 From: Alex Boten Date: Wed, 20 Apr 2022 11:23:32 -0700 Subject: [PATCH] [docs] SDK documentation fixes (#2620) --- docs/api/metrics.instrument.rst | 2 +- docs/conf.py | 21 ++++++++++++++++++- docs/sdk/metrics.export.rst | 7 +++++++ docs/sdk/metrics.point.rst | 7 +++++++ docs/sdk/metrics.rst | 2 ++ .../src/opentelemetry/_metrics/__init__.py | 2 +- .../src/opentelemetry/_metrics/instrument.py | 14 +++++++++++++ .../opentelemetry/sdk/_metrics/aggregation.py | 20 +++++++++--------- .../sdk/_metrics/export/__init__.py | 4 ++-- 9 files changed, 64 insertions(+), 15 deletions(-) create mode 100644 docs/sdk/metrics.export.rst create mode 100644 docs/sdk/metrics.point.rst diff --git a/docs/api/metrics.instrument.rst b/docs/api/metrics.instrument.rst index 4a678ef07f1..7d23f6fa773 100644 --- a/docs/api/metrics.instrument.rst +++ b/docs/api/metrics.instrument.rst @@ -5,4 +5,4 @@ opentelemetry._metrics.instrument :members: :private-members: :undoc-members: - :show-inheritance: + :no-show-inheritance: diff --git a/docs/conf.py b/docs/conf.py index 4f2458d1e74..d250de2b530 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -142,12 +142,31 @@ "examples/error_handler/error_handler_1", ] +_exclude_members = [ + "_ProxyObservableUpDownCounter", + "_ProxyHistogram", + "_ProxyObservableGauge", + "_ProxyInstrument", + "_ProxyAsynchronousInstrument", + "_ProxyCounter", + "_ProxyUpDownCounter", + "_ProxyObservableCounter", + "_ProxyObservableGauge", + "_abc_impl", + "_Adding", + "_Grouping", + "_Monotonic", + "_NonMonotonic", + "Synchronous", + "Asynchronous", +] + autodoc_default_options = { "members": True, "undoc-members": True, "show-inheritance": True, "member-order": "bysource", - "exclude-members": "_ProxyObservableUpDownCounter,_ProxyHistogram,_ProxyObservableGauge,_ProxyInstrument,_ProxyAsynchronousInstrument,_ProxyCounter,_ProxyUpDownCounter,_ProxyObservableCounter,_ProxyObservableGauge,_abc_impl", + "exclude-members": ",".join(_exclude_members), } # -- Options for HTML output ------------------------------------------------- diff --git a/docs/sdk/metrics.export.rst b/docs/sdk/metrics.export.rst new file mode 100644 index 00000000000..775c0a66111 --- /dev/null +++ b/docs/sdk/metrics.export.rst @@ -0,0 +1,7 @@ +opentelemetry.sdk._metrics.export +================================= + +.. automodule:: opentelemetry.sdk._metrics.export + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sdk/metrics.point.rst b/docs/sdk/metrics.point.rst new file mode 100644 index 00000000000..b19f27c460b --- /dev/null +++ b/docs/sdk/metrics.point.rst @@ -0,0 +1,7 @@ +opentelemetry.sdk._metrics.point +================================ + +.. automodule:: opentelemetry.sdk._metrics.point + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/sdk/metrics.rst b/docs/sdk/metrics.rst index 76bb064b52f..d62ad456b32 100644 --- a/docs/sdk/metrics.rst +++ b/docs/sdk/metrics.rst @@ -16,6 +16,8 @@ Submodules metrics.view metrics.aggregation metrics.metric_reader + metrics.point + metrics.export .. automodule:: opentelemetry.sdk._metrics :members: diff --git a/opentelemetry-api/src/opentelemetry/_metrics/__init__.py b/opentelemetry-api/src/opentelemetry/_metrics/__init__.py index a42cfd53f37..30b9230be54 100644 --- a/opentelemetry-api/src/opentelemetry/_metrics/__init__.py +++ b/opentelemetry-api/src/opentelemetry/_metrics/__init__.py @@ -331,7 +331,7 @@ def cpu_time_callback(states_to_include: set[str]) -> Iterable[Iterable[Observat @abstractmethod def create_histogram(self, name, unit="", description="") -> Histogram: - """Creates a `Histogram` instrument + """Creates a `opentelemetry._metrics.instrument.Histogram` instrument Args: name: The name of the instrument to be created diff --git a/opentelemetry-api/src/opentelemetry/_metrics/instrument.py b/opentelemetry-api/src/opentelemetry/_metrics/instrument.py index 0718a312e85..d79b0d9aa60 100644 --- a/opentelemetry-api/src/opentelemetry/_metrics/instrument.py +++ b/opentelemetry-api/src/opentelemetry/_metrics/instrument.py @@ -43,6 +43,8 @@ class Instrument(ABC): + """Abstract class that serves as base for all instruments.""" + @abstractmethod def __init__(self, name, unit="", description=""): pass @@ -120,6 +122,8 @@ def add(self, amount, attributes=None): class NoOpCounter(Counter): + """No-op implementation of `Counter`.""" + def __init__(self, name, unit="", description=""): super().__init__(name, unit=unit, description=description) @@ -145,6 +149,8 @@ def add(self, amount, attributes=None): class NoOpUpDownCounter(UpDownCounter): + """No-op implementation of `UpDownCounter`.""" + def __init__(self, name, unit="", description=""): super().__init__(name, unit=unit, description=description) @@ -170,6 +176,8 @@ class ObservableCounter(_Monotonic, Asynchronous): class NoOpObservableCounter(ObservableCounter): + """No-op implementation of `ObservableCounter`.""" + def __init__(self, name, callbacks=None, unit="", description=""): super().__init__(name, callbacks, unit=unit, description=description) @@ -193,6 +201,8 @@ class ObservableUpDownCounter(_NonMonotonic, Asynchronous): class NoOpObservableUpDownCounter(ObservableUpDownCounter): + """No-op implementation of `ObservableUpDownCounter`.""" + def __init__(self, name, callbacks=None, unit="", description=""): super().__init__(name, callbacks, unit=unit, description=description) @@ -221,6 +231,8 @@ def record(self, amount, attributes=None): class NoOpHistogram(Histogram): + """No-op implementation of `Histogram`.""" + def __init__(self, name, unit="", description=""): super().__init__(name, unit=unit, description=description) @@ -247,6 +259,8 @@ class ObservableGauge(_Grouping, Asynchronous): class NoOpObservableGauge(ObservableGauge): + """No-op implementation of `ObservableGauge`.""" + def __init__(self, name, callbacks=None, unit="", description=""): super().__init__(name, callbacks, unit=unit, description=description) diff --git a/opentelemetry-sdk/src/opentelemetry/sdk/_metrics/aggregation.py b/opentelemetry-sdk/src/opentelemetry/sdk/_metrics/aggregation.py index c6ecff0cfa7..ec6497e9c94 100644 --- a/opentelemetry-sdk/src/opentelemetry/sdk/_metrics/aggregation.py +++ b/opentelemetry-sdk/src/opentelemetry/sdk/_metrics/aggregation.py @@ -82,16 +82,16 @@ class DefaultAggregation(_AggregationFactory): This aggregation will create an actual aggregation depending on the instrument type, as specified next: - ========================= ==================================== - Instrument Aggregation - ========================= ==================================== - `Counter` `SumAggregation` - `UpDownCounter` `SumAggregation` - `ObservableCounter` `SumAggregation` - `ObservableUpDownCounter` `SumAggregation` - `Histogram` `ExplicitBucketHistogramAggregation` - `ObservableGauge` `LastValueAggregation` - ========================= ==================================== + ============================================= ==================================== + Instrument Aggregation + ============================================= ==================================== + `Counter` `SumAggregation` + `UpDownCounter` `SumAggregation` + `ObservableCounter` `SumAggregation` + `ObservableUpDownCounter` `SumAggregation` + `opentelemetry._metrics.instrument.Histogram` `ExplicitBucketHistogramAggregation` + `ObservableGauge` `LastValueAggregation` + ============================================= ==================================== """ def _create_aggregation(self, instrument: Instrument) -> _Aggregation: diff --git a/opentelemetry-sdk/src/opentelemetry/sdk/_metrics/export/__init__.py b/opentelemetry-sdk/src/opentelemetry/sdk/_metrics/export/__init__.py index 9145f4e0fbb..ff505ed4dfc 100644 --- a/opentelemetry-sdk/src/opentelemetry/sdk/_metrics/export/__init__.py +++ b/opentelemetry-sdk/src/opentelemetry/sdk/_metrics/export/__init__.py @@ -55,7 +55,7 @@ def export(self, metrics: Sequence[Metric]) -> "MetricExportResult": """Exports a batch of telemetry data. Args: - metrics: The list of `opentelemetry.sdk._metrics.data.MetricData` objects to be exported + metrics: The list of `opentelemetry.sdk._metrics.point.Metric` objects to be exported Returns: The result of the export @@ -97,7 +97,7 @@ def shutdown(self) -> None: class InMemoryMetricReader(MetricReader): - """Implementation of :class:`MetricReader` that returns its metrics from :func:`metrics`. + """Implementation of `MetricReader` that returns its metrics from :func:`get_metrics`. This is useful for e.g. unit tests. """