From 9a9d3ab55309cfff7b2baeab6b1fe2b36f5bf0cf Mon Sep 17 00:00:00 2001 From: John Scancella Date: Mon, 18 Aug 2025 19:17:23 -0400 Subject: [PATCH 1/9] docs: updated the ReadTheDocs documentation to all have links to the examples for consistency --- docs/examples/django/README.rst | 2 +- docs/examples/error_handler/README.rst | 1 + docs/examples/fork-process-model/README.rst | 5 +- docs/examples/logs/README.rst | 2 + docs/examples/metrics/instruments/README.rst | 2 + .../metrics/prometheus-grafana/README.rst | 63 +++++++++++++++++++ .../prometheus-grafana/prometheus-monitor.py | 2 + 7 files changed, 73 insertions(+), 4 deletions(-) create mode 100644 docs/examples/metrics/prometheus-grafana/README.rst diff --git a/docs/examples/django/README.rst b/docs/examples/django/README.rst index 1dd8999c036..4f1771fbe68 100644 --- a/docs/examples/django/README.rst +++ b/docs/examples/django/README.rst @@ -4,7 +4,7 @@ Django Instrumentation This shows how to use ``opentelemetry-instrumentation-django`` to automatically instrument a Django app. -For more user convenience, a Django app is already provided in this directory. +The source files of these examples are available :scm_web:`here `. Preparation ----------- diff --git a/docs/examples/error_handler/README.rst b/docs/examples/error_handler/README.rst index b879e53e9bf..178a0b889f9 100644 --- a/docs/examples/error_handler/README.rst +++ b/docs/examples/error_handler/README.rst @@ -6,6 +6,7 @@ Overview This example shows how to use the global error handler. +The source files of these examples are available :scm_web:`here `. Preparation ----------- diff --git a/docs/examples/fork-process-model/README.rst b/docs/examples/fork-process-model/README.rst index 2f33bcf500a..a154fc1249a 100644 --- a/docs/examples/fork-process-model/README.rst +++ b/docs/examples/fork-process-model/README.rst @@ -10,6 +10,8 @@ get around this limitation of the span processor. Please see http://bugs.python.org/issue6721 for the problems about Python locks in (multi)threaded context with fork. +The source code for the examples with Flask app are available :scm_web:`here `. + Gunicorn post_fork hook ----------------------- @@ -61,6 +63,3 @@ uWSGI postfork decorator OTLPSpanExporter(endpoint="http://localhost:4317") ) trace.get_tracer_provider().add_span_processor(span_processor) - - -The source code for the examples with Flask app are available :scm_web:`here `. diff --git a/docs/examples/logs/README.rst b/docs/examples/logs/README.rst index e3cd86362b2..d58c575bac4 100644 --- a/docs/examples/logs/README.rst +++ b/docs/examples/logs/README.rst @@ -6,6 +6,8 @@ OpenTelemetry Logs SDK :mod:`opentelemetry.sdk._logs` are subject to change in minor/patch releases and make no backward compatibility guarantees at this time. +The source files of these examples are available :scm_web:`here `. + Start the Collector locally to see data being exported. Write the following file: .. code-block:: yaml diff --git a/docs/examples/metrics/instruments/README.rst b/docs/examples/metrics/instruments/README.rst index bbc9f457bb7..dffdd02657b 100644 --- a/docs/examples/metrics/instruments/README.rst +++ b/docs/examples/metrics/instruments/README.rst @@ -1,6 +1,8 @@ OpenTelemetry Metrics SDK ========================= +The source files of these examples are available :scm_web:`here `. + Start the Collector locally to see data being exported. Write the following file: .. code-block:: yaml diff --git a/docs/examples/metrics/prometheus-grafana/README.rst b/docs/examples/metrics/prometheus-grafana/README.rst new file mode 100644 index 00000000000..7cafacb153a --- /dev/null +++ b/docs/examples/metrics/prometheus-grafana/README.rst @@ -0,0 +1,63 @@ +Prometheus Instrumentation +========================== + +This shows how to use ``opentelemetry-exporter-prometheus`` to automatically generate prometheus metrics. + +The source files of these examples are available :scm_web:`here `. + +Preparation +----------- + +This example will be executed in a separate virtual environment: + +.. code-block:: + + $ mkdir prometheus_auto_instrumentation + $ virtualenv prometheus_auto_instrumentation + $ source prometheus_auto_instrumentation/bin/activate + + +Installation +------------ + +.. code-block:: + + $ pip install -r requirements.txt + + +Execution +--------- + +.. code-block:: + + $ python ./prometheus-monitor.py + $ Server is running at http://localhost:8000 + +Now you can visit `localhost:8000/metrics ` to see prometheus metrics. +You should see something like: + +.. code-block:: + + # HELP python_gc_objects_collected_total Objects collected during gc + # TYPE python_gc_objects_collected_total counter + python_gc_objects_collected_total{generation="0"} 320.0 + python_gc_objects_collected_total{generation="1"} 58.0 + python_gc_objects_collected_total{generation="2"} 0.0 + # HELP python_gc_objects_uncollectable_total Uncollectable objects found during GC + # TYPE python_gc_objects_uncollectable_total counter + python_gc_objects_uncollectable_total{generation="0"} 0.0 + python_gc_objects_uncollectable_total{generation="1"} 0.0 + python_gc_objects_uncollectable_total{generation="2"} 0.0 + # HELP python_gc_collections_total Number of times this generation was collected + # TYPE python_gc_collections_total counter + python_gc_collections_total{generation="0"} 61.0 + python_gc_collections_total{generation="1"} 5.0 + python_gc_collections_total{generation="2"} 0.0 + # HELP python_info Python platform information + # TYPE python_info gauge + python_info{implementation="CPython",major="3",minor="8",patchlevel="5",version="3.8.5"} 1.0 + # HELP MyAppPrefix_my_counter_total + # TYPE MyAppPrefix_my_counter_total counter + MyAppPrefix_my_counter_total 964.0 + +`MyAppPrefix_my_counter_total` is the custom counter created in the application with the custom prefix `MyAppPrefix`. \ No newline at end of file diff --git a/docs/examples/metrics/prometheus-grafana/prometheus-monitor.py b/docs/examples/metrics/prometheus-grafana/prometheus-monitor.py index 17a837d5a58..709b0b9e758 100644 --- a/docs/examples/metrics/prometheus-grafana/prometheus-monitor.py +++ b/docs/examples/metrics/prometheus-grafana/prometheus-monitor.py @@ -18,6 +18,8 @@ my_counter = meter.create_counter("my.counter") +print("Server is running at http://localhost:8000") + while 1: my_counter.add(random.randint(1, 10)) time.sleep(random.random()) From f4e4fca5e6cae085402b9acbb6d7f9f397a1f797 Mon Sep 17 00:00:00 2001 From: John Scancella Date: Tue, 19 Aug 2025 12:22:25 -0400 Subject: [PATCH 2/9] Update docs/examples/metrics/prometheus-grafana/README.rst Co-authored-by: Tammy Baylis <96076570+tammy-baylis-swi@users.noreply.github.com> --- docs/examples/metrics/prometheus-grafana/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples/metrics/prometheus-grafana/README.rst b/docs/examples/metrics/prometheus-grafana/README.rst index 7cafacb153a..8474f987dad 100644 --- a/docs/examples/metrics/prometheus-grafana/README.rst +++ b/docs/examples/metrics/prometheus-grafana/README.rst @@ -33,7 +33,7 @@ Execution $ python ./prometheus-monitor.py $ Server is running at http://localhost:8000 -Now you can visit `localhost:8000/metrics ` to see prometheus metrics. +Now you can visit `localhost:8000/metrics ` to see Prometheus metrics. You should see something like: .. code-block:: From 42686d25dbe80030f6d0dd3bddc075aa56960285 Mon Sep 17 00:00:00 2001 From: John Scancella Date: Tue, 19 Aug 2025 12:29:34 -0400 Subject: [PATCH 3/9] Added changelog entry as requested in PR feedback --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ad6b1bfe8d5..70b6e0ddd95 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased ## Version 1.36.0/0.57b0 (2025-07-29) +- Updated Read The Docs linking the examples with their github source code location and added Prometheus example. + ([#4728](https://github.com/open-telemetry/opentelemetry-python/pull/4728)) - Add missing Prometheus exporter documentation ([#4485](https://github.com/open-telemetry/opentelemetry-python/pull/4485)) From 8ca5f6da38c3c65b56d9e01aee2d97176ca9fe17 Mon Sep 17 00:00:00 2001 From: John Scancella Date: Tue, 19 Aug 2025 12:31:44 -0400 Subject: [PATCH 4/9] fixed link to localhost to see the metrics --- docs/examples/metrics/prometheus-grafana/README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/examples/metrics/prometheus-grafana/README.rst b/docs/examples/metrics/prometheus-grafana/README.rst index 8474f987dad..77ac5b424d2 100644 --- a/docs/examples/metrics/prometheus-grafana/README.rst +++ b/docs/examples/metrics/prometheus-grafana/README.rst @@ -33,7 +33,7 @@ Execution $ python ./prometheus-monitor.py $ Server is running at http://localhost:8000 -Now you can visit `localhost:8000/metrics ` to see Prometheus metrics. +Now you can visit `http://localhost:8000/metrics` to see Prometheus metrics. You should see something like: .. code-block:: @@ -60,4 +60,4 @@ You should see something like: # TYPE MyAppPrefix_my_counter_total counter MyAppPrefix_my_counter_total 964.0 -`MyAppPrefix_my_counter_total` is the custom counter created in the application with the custom prefix `MyAppPrefix`. \ No newline at end of file +`MyAppPrefix_my_counter_total` is the custom counter created in the application with the custom prefix `MyAppPrefix`. From e9b0aa8a32d27697205d73fd40ba03db07facc37 Mon Sep 17 00:00:00 2001 From: John Scancella Date: Tue, 19 Aug 2025 14:07:21 -0400 Subject: [PATCH 5/9] just use a plain http link --- docs/examples/metrics/prometheus-grafana/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples/metrics/prometheus-grafana/README.rst b/docs/examples/metrics/prometheus-grafana/README.rst index 77ac5b424d2..fa4e80c4b2a 100644 --- a/docs/examples/metrics/prometheus-grafana/README.rst +++ b/docs/examples/metrics/prometheus-grafana/README.rst @@ -33,7 +33,7 @@ Execution $ python ./prometheus-monitor.py $ Server is running at http://localhost:8000 -Now you can visit `http://localhost:8000/metrics` to see Prometheus metrics. +Now you can visit http://localhost:8000/metrics to see Prometheus metrics. You should see something like: .. code-block:: From f3fbd1e33e21821fff5a7bfea22eb3e8ff3ab729 Mon Sep 17 00:00:00 2001 From: John Scancella Date: Thu, 21 Aug 2025 17:35:18 -0400 Subject: [PATCH 6/9] Update CHANGELOG.md Co-authored-by: Riccardo Magliocchetti --- CHANGELOG.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 70b6e0ddd95..ee04e8f2d63 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,10 +12,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased -## Version 1.36.0/0.57b0 (2025-07-29) -- Updated Read The Docs linking the examples with their github source code location and added Prometheus example. +- docs: linked the examples with their github source code location and added Prometheus example ([#4728](https://github.com/open-telemetry/opentelemetry-python/pull/4728)) +## Version 1.36.0/0.57b0 (2025-07-29) + + - Add missing Prometheus exporter documentation ([#4485](https://github.com/open-telemetry/opentelemetry-python/pull/4485)) - Overwrite logging.config.fileConfig and logging.config.dictConfig to ensure From 67601f52020927425dd56bd36263a2098822a23d Mon Sep 17 00:00:00 2001 From: John Scancella Date: Thu, 21 Aug 2025 18:46:52 -0400 Subject: [PATCH 7/9] fix tox reported issues --- docs/examples/metrics/prometheus-grafana/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples/metrics/prometheus-grafana/README.rst b/docs/examples/metrics/prometheus-grafana/README.rst index fa4e80c4b2a..9e9def2edb6 100644 --- a/docs/examples/metrics/prometheus-grafana/README.rst +++ b/docs/examples/metrics/prometheus-grafana/README.rst @@ -60,4 +60,4 @@ You should see something like: # TYPE MyAppPrefix_my_counter_total counter MyAppPrefix_my_counter_total 964.0 -`MyAppPrefix_my_counter_total` is the custom counter created in the application with the custom prefix `MyAppPrefix`. +``MyAppPrefix_my_counter_total`` is the custom counter created in the application with the custom prefix ``MyAppPrefix``. From 93bff97e853f0f41edd84a6a31903bff046568d7 Mon Sep 17 00:00:00 2001 From: John Scancella Date: Thu, 21 Aug 2025 18:48:26 -0400 Subject: [PATCH 8/9] fix capitalization of Prometheus --- docs/examples/metrics/prometheus-grafana/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples/metrics/prometheus-grafana/README.rst b/docs/examples/metrics/prometheus-grafana/README.rst index 9e9def2edb6..649317c4dc8 100644 --- a/docs/examples/metrics/prometheus-grafana/README.rst +++ b/docs/examples/metrics/prometheus-grafana/README.rst @@ -1,7 +1,7 @@ Prometheus Instrumentation ========================== -This shows how to use ``opentelemetry-exporter-prometheus`` to automatically generate prometheus metrics. +This shows how to use ``opentelemetry-exporter-prometheus`` to automatically generate Prometheus metrics. The source files of these examples are available :scm_web:`here `. From 7e685255676084740739fd9b5d6706640fecac18 Mon Sep 17 00:00:00 2001 From: Riccardo Magliocchetti Date: Fri, 22 Aug 2025 16:30:21 +0200 Subject: [PATCH 9/9] Update CHANGELOG.md --- CHANGELOG.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ee04e8f2d63..641e0da140a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,7 +17,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Version 1.36.0/0.57b0 (2025-07-29) - - Add missing Prometheus exporter documentation ([#4485](https://github.com/open-telemetry/opentelemetry-python/pull/4485)) - Overwrite logging.config.fileConfig and logging.config.dictConfig to ensure