From 7427ff7cec5da24a9f6381a90c3f87dbf099f944 Mon Sep 17 00:00:00 2001 From: Riccardo Magliocchetti Date: Mon, 20 Jul 2026 15:14:35 +0200 Subject: [PATCH 1/7] docs/examples/metrics: add example on how to manually setup sdk for health metrics --- docs/examples/metrics/sdk-metrics/README.rst | 36 +++++++++ .../metrics/sdk-metrics/requirements.txt | 4 + .../metrics/sdk-metrics/sdk_metrics.py | 80 +++++++++++++++++++ 3 files changed, 120 insertions(+) create mode 100644 docs/examples/metrics/sdk-metrics/README.rst create mode 100644 docs/examples/metrics/sdk-metrics/requirements.txt create mode 100644 docs/examples/metrics/sdk-metrics/sdk_metrics.py diff --git a/docs/examples/metrics/sdk-metrics/README.rst b/docs/examples/metrics/sdk-metrics/README.rst new file mode 100644 index 00000000000..1ef4b3dfca7 --- /dev/null +++ b/docs/examples/metrics/sdk-metrics/README.rst @@ -0,0 +1,36 @@ +SDK Metrics +=========== + +Some SDK components can emit telemetry about their internal state according to the `semantic conventions for OpenTelemetry SDK metrics ` + +The provided :scm_web:`sdk_metrics.py ` example shows how to setup manually the SDK in order to send them. + +Installation +------------ + +.. code-block:: sh + + pip install -r requirements.txt + +Run the Example +--------------- + +Start an OTLP HTTP collector or compatible backend listening on the default +endpoint, ``http://localhost:4318``. To use a different endpoint, configure +``OTEL_EXPORTER_OTLP_ENDPOINT`` or the signal-specific OTLP exporter +environment variables. + +.. code-block:: sh + + python sdk_metrics.py + +The example sends a span, a log record, and the OpenTelemetry SDK health +metrics emitted by the configured SDK components. + +Useful links +------------ + +- OpenTelemetry_ +- :doc:`../../../api/metrics` + +.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/ diff --git a/docs/examples/metrics/sdk-metrics/requirements.txt b/docs/examples/metrics/sdk-metrics/requirements.txt new file mode 100644 index 00000000000..84b530cd773 --- /dev/null +++ b/docs/examples/metrics/sdk-metrics/requirements.txt @@ -0,0 +1,4 @@ +opentelemetry-api==1.44.0 +opentelemetry-exporter-otlp-proto-http==1.44.0 +opentelemetry-sdk==1.44.0 +opentelemetry-semantic-conventions==0.65b0 diff --git a/docs/examples/metrics/sdk-metrics/sdk_metrics.py b/docs/examples/metrics/sdk-metrics/sdk_metrics.py new file mode 100644 index 00000000000..c47527f9ddb --- /dev/null +++ b/docs/examples/metrics/sdk-metrics/sdk_metrics.py @@ -0,0 +1,80 @@ +# Copyright The OpenTelemetry Authors +# SPDX-License-Identifier: Apache-2.0 + +import os +import time + +from opentelemetry import _logs, metrics, trace +from opentelemetry.exporter.otlp.proto.http._log_exporter import ( + OTLPLogExporter, +) +from opentelemetry.exporter.otlp.proto.http.metric_exporter import ( + OTLPMetricExporter, +) +from opentelemetry.exporter.otlp.proto.http.trace_exporter import ( + OTLPSpanExporter, +) +from opentelemetry.sdk._logs import LoggerProvider +from opentelemetry.sdk._logs.export import SimpleLogRecordProcessor +from opentelemetry.sdk.metrics import MeterProvider +from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader +from opentelemetry.sdk.resources import Resource +from opentelemetry.sdk.trace import TracerProvider +from opentelemetry.sdk.trace.export import SimpleSpanProcessor + +os.environ.setdefault("OTEL_PYTHON_SDK_INTERNAL_METRICS_ENABLED", "true") + +resource = Resource.create({"service.name": "sdk-metrics-example"}) + +meter_provider = MeterProvider(resource=resource) +metrics.set_meter_provider(meter_provider) + +# Pass the metrics provider into each SDK component that should report +# internal health metrics. +metric_exporter = OTLPMetricExporter(meter_provider=meter_provider) +metric_reader = PeriodicExportingMetricReader( + metric_exporter, + export_interval_millis=250, +) +meter_provider.add_metric_reader(metric_reader) + +tracer_provider = TracerProvider( + resource=resource, + meter_provider=meter_provider, +) +tracer_provider.add_span_processor( + SimpleSpanProcessor( + OTLPSpanExporter(meter_provider=meter_provider), + meter_provider=meter_provider, + ) +) +trace.set_tracer_provider(tracer_provider) + +logger_provider = LoggerProvider( + resource=resource, + meter_provider=meter_provider, +) +logger_provider.add_log_record_processor( + SimpleLogRecordProcessor( + OTLPLogExporter(meter_provider=meter_provider), + meter_provider=meter_provider, + ) +) +_logs.set_logger_provider(logger_provider) + +tracer = trace.get_tracer(__name__) +logger = _logs.get_logger(__name__) + +with tracer.start_as_current_span("example-span"): + logger.emit(body="example log record") + # Let the periodic reader export at least once so exporter self-metrics + # are available for the final metrics export. + time.sleep(0.5) + +tracer_provider.force_flush() +logger_provider.force_flush() +meter_provider.force_flush() + +tracer_provider.shutdown() +logger_provider.shutdown() +meter_provider.shutdown() From ad460abd1e4ad5e50bf79e82198b6438ace4f969 Mon Sep 17 00:00:00 2001 From: Riccardo Magliocchetti Date: Mon, 20 Jul 2026 16:22:26 +0200 Subject: [PATCH 2/7] Add changelog --- .changelog/5449.added | 1 + 1 file changed, 1 insertion(+) create mode 100644 .changelog/5449.added diff --git a/.changelog/5449.added b/.changelog/5449.added new file mode 100644 index 00000000000..52d73c09635 --- /dev/null +++ b/.changelog/5449.added @@ -0,0 +1 @@ +`docs/examples`: add example on how to manually setup the SDK to get SDK metrics From ec4caa5709381ea8f6950bb7a253dfebbd96a9b3 Mon Sep 17 00:00:00 2001 From: Riccardo Magliocchetti Date: Tue, 21 Jul 2026 09:44:49 +0200 Subject: [PATCH 3/7] Make it explicit that these are still in development --- docs/examples/metrics/sdk-metrics/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples/metrics/sdk-metrics/README.rst b/docs/examples/metrics/sdk-metrics/README.rst index 1ef4b3dfca7..a59f53a38e5 100644 --- a/docs/examples/metrics/sdk-metrics/README.rst +++ b/docs/examples/metrics/sdk-metrics/README.rst @@ -1,7 +1,7 @@ SDK Metrics =========== -Some SDK components can emit telemetry about their internal state according to the `semantic conventions for OpenTelemetry SDK metrics ` +Some SDK components can emit telemetry about their internal state according to the `semantic conventions for OpenTelemetry SDK metrics `. At the time of writing these semantic conventions are still in development and in order to have then exported you need to set the ``OTEL_PYTHON_SDK_INTERNAL_METRICS_ENABLED`` environment variable to ``true``. The provided :scm_web:`sdk_metrics.py ` example shows how to setup manually the SDK in order to send them. From 79c909d0f9a65c984c20724754d15bceb4f22b4b Mon Sep 17 00:00:00 2001 From: Riccardo Magliocchetti Date: Tue, 21 Jul 2026 09:45:46 +0200 Subject: [PATCH 4/7] Typo --- docs/examples/metrics/sdk-metrics/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples/metrics/sdk-metrics/README.rst b/docs/examples/metrics/sdk-metrics/README.rst index a59f53a38e5..abaa0b90d15 100644 --- a/docs/examples/metrics/sdk-metrics/README.rst +++ b/docs/examples/metrics/sdk-metrics/README.rst @@ -1,7 +1,7 @@ SDK Metrics =========== -Some SDK components can emit telemetry about their internal state according to the `semantic conventions for OpenTelemetry SDK metrics `. At the time of writing these semantic conventions are still in development and in order to have then exported you need to set the ``OTEL_PYTHON_SDK_INTERNAL_METRICS_ENABLED`` environment variable to ``true``. +Some SDK components can emit telemetry about their internal state according to the `semantic conventions for OpenTelemetry SDK metrics `. At the time of writing these semantic conventions are still in development and in order to have them exported you need to set the ``OTEL_PYTHON_SDK_INTERNAL_METRICS_ENABLED`` environment variable to ``true``. The provided :scm_web:`sdk_metrics.py ` example shows how to setup manually the SDK in order to send them. From 265c5a4013cad76368cb3b664d8d69c556382fb6 Mon Sep 17 00:00:00 2001 From: Riccardo Magliocchetti Date: Fri, 24 Jul 2026 17:17:22 +0200 Subject: [PATCH 5/7] Fix external link syntax --- docs/examples/metrics/sdk-metrics/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples/metrics/sdk-metrics/README.rst b/docs/examples/metrics/sdk-metrics/README.rst index abaa0b90d15..64c500a3bbc 100644 --- a/docs/examples/metrics/sdk-metrics/README.rst +++ b/docs/examples/metrics/sdk-metrics/README.rst @@ -1,7 +1,7 @@ SDK Metrics =========== -Some SDK components can emit telemetry about their internal state according to the `semantic conventions for OpenTelemetry SDK metrics `. At the time of writing these semantic conventions are still in development and in order to have them exported you need to set the ``OTEL_PYTHON_SDK_INTERNAL_METRICS_ENABLED`` environment variable to ``true``. +Some SDK components can emit telemetry about their internal state according to the `semantic conventions for OpenTelemetry SDK metrics `_. At the time of writing these semantic conventions are still in development and in order to have them exported you need to set the ``OTEL_PYTHON_SDK_INTERNAL_METRICS_ENABLED`` environment variable to ``true``. The provided :scm_web:`sdk_metrics.py ` example shows how to setup manually the SDK in order to send them. From 82852aed385a0bd7c8804031a4ea5cf07f91ea49 Mon Sep 17 00:00:00 2001 From: Riccardo Magliocchetti Date: Fri, 24 Jul 2026 17:49:23 +0200 Subject: [PATCH 6/7] Apply suggestion from @emdneto MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Emídio <9735060+emdneto@users.noreply.github.com> --- docs/examples/metrics/sdk-metrics/sdk_metrics.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples/metrics/sdk-metrics/sdk_metrics.py b/docs/examples/metrics/sdk-metrics/sdk_metrics.py index c47527f9ddb..7b215bb880a 100644 --- a/docs/examples/metrics/sdk-metrics/sdk_metrics.py +++ b/docs/examples/metrics/sdk-metrics/sdk_metrics.py @@ -34,7 +34,7 @@ metric_exporter = OTLPMetricExporter(meter_provider=meter_provider) metric_reader = PeriodicExportingMetricReader( metric_exporter, - export_interval_millis=250, + export_interval_millis=250, # Intentionally low for example purposes only ) meter_provider.add_metric_reader(metric_reader) From ef13b8ebabdbe74b5dee7caea021aa6dbf776350 Mon Sep 17 00:00:00 2001 From: Riccardo Magliocchetti Date: Fri, 24 Jul 2026 17:52:19 +0200 Subject: [PATCH 7/7] Precommit --- docs/examples/metrics/sdk-metrics/sdk_metrics.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples/metrics/sdk-metrics/sdk_metrics.py b/docs/examples/metrics/sdk-metrics/sdk_metrics.py index 7b215bb880a..23a9c11d391 100644 --- a/docs/examples/metrics/sdk-metrics/sdk_metrics.py +++ b/docs/examples/metrics/sdk-metrics/sdk_metrics.py @@ -34,7 +34,7 @@ metric_exporter = OTLPMetricExporter(meter_provider=meter_provider) metric_reader = PeriodicExportingMetricReader( metric_exporter, - export_interval_millis=250, # Intentionally low for example purposes only + export_interval_millis=250, # Intentionally low for example purposes only ) meter_provider.add_metric_reader(metric_reader)