diff --git a/docs-requirements.txt b/docs-requirements.txt index 41600cfe8c..2b8f732401 100644 --- a/docs-requirements.txt +++ b/docs-requirements.txt @@ -11,3 +11,4 @@ flask~=1.0 mysql-connector-python ~= 8.0 wrapt >= 1.0.0, < 2.0.0 psycopg2-binary >= 2.7.3.1 +prometheus_client >= 0.5.0, < 1.0.0 diff --git a/docs/examples/basic_meter/README.rst b/docs/examples/basic_meter/README.rst new file mode 100644 index 0000000000..a48e5bb612 --- /dev/null +++ b/docs/examples/basic_meter/README.rst @@ -0,0 +1,42 @@ +Basic Meter +=========== + +These examples show how to use OpenTelemetry to capture and report metrics. + +There are three different examples: + +* basic_metrics: Shows to how create a metric instrument, how to configure an + exporter and a controller and also how to capture data by using the direct + calling convention. + +* calling_conventions: Shows how to use the direct, bound and batch calling conventions. + +* observer: Shows how to use the observer instrument. + +The source files of these examples are available :scm_web:`here `. + +Installation +------------ + +.. code-block:: sh + + pip install opentelemetry-api + pip install opentelemetry-sdk + pip install psutil # needed to get ram and cpu usage in the observer example + +Run the Example +--------------- + +.. code-block:: sh + + python .py + +The output will be shown in the console after few seconds. + +Useful links +------------ + +- OpenTelemetry_ +- :doc:`../../api/metrics` + +.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/ diff --git a/docs/examples/metrics/simple_example.py b/docs/examples/basic_meter/basic_metrics.py similarity index 91% rename from docs/examples/metrics/simple_example.py rename to docs/examples/basic_meter/basic_metrics.py index a0152b29f3..ac06284c32 100644 --- a/docs/examples/metrics/simple_example.py +++ b/docs/examples/basic_meter/basic_metrics.py @@ -13,7 +13,8 @@ # limitations under the License. # """ -This module serves as an example for a simple application using metrics +This module serves as an example for a simple application using metrics. + It shows: - How to configure a meter passing a sateful or stateless. - How to configure an exporter and how to create a controller. @@ -27,7 +28,7 @@ from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter from opentelemetry.sdk.metrics.export.controller import PushController -batcher_mode = "stateful" +stateful = True def usage(argv): @@ -42,6 +43,11 @@ def usage(argv): print("bad mode specified.") usage(sys.argv) sys.exit(1) + stateful = batcher_mode == "stateful" + +print( + "Starting example, values will be printed to the console every 5 seconds." +) # The Meter is responsible for creating and recording metrics. Each meter has a @@ -57,7 +63,7 @@ def usage(argv): # A PushController collects metrics created from meter and exports it via the # exporter every interval -controller = PushController(meter, exporter, 5) +controller = PushController(meter=meter, exporter=exporter, interval=5) # Metric instruments allow to capture measurements requests_counter = meter.create_metric( @@ -69,15 +75,6 @@ def usage(argv): label_keys=("environment",), ) -clicks_counter = meter.create_metric( - name="clicks", - description="number of clicks", - unit="1", - value_type=int, - metric_type=Counter, - label_keys=("environment",), -) - requests_size = meter.create_metric( name="requests_size", description="size of requests", @@ -94,17 +91,14 @@ def usage(argv): testing_label_set = meter.get_label_set({"environment": "testing"}) # Update the metric instruments using the direct calling convention -requests_size.record(100, staging_label_set) requests_counter.add(25, staging_label_set) +requests_size.record(100, staging_label_set) time.sleep(5) -requests_size.record(5000, staging_label_set) requests_counter.add(50, staging_label_set) +requests_size.record(5000, staging_label_set) time.sleep(5) -requests_size.record(2, testing_label_set) requests_counter.add(35, testing_label_set) -time.sleep(5) - -clicks_counter.add(5, staging_label_set) +requests_size.record(2, testing_label_set) time.sleep(5) diff --git a/docs/examples/metrics/record.py b/docs/examples/basic_meter/calling_conventions.py similarity index 64% rename from docs/examples/metrics/record.py rename to docs/examples/basic_meter/calling_conventions.py index e1c7901fa0..946dccda62 100644 --- a/docs/examples/metrics/record.py +++ b/docs/examples/basic_meter/calling_conventions.py @@ -13,28 +13,23 @@ # limitations under the License. # """ -This module serves as an example for a simple application using metrics. -It demonstrates the different ways you can record metrics via the meter. +This example shows how to use the different modes to capture metrics. +It shows the usage of the direct, bound and batch calling conventions. """ import time from opentelemetry import metrics -from opentelemetry.sdk.metrics import Counter, MeterProvider +from opentelemetry.sdk.metrics import Counter, Measure, MeterProvider from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter from opentelemetry.sdk.metrics.export.controller import PushController # Use the meter type provided by the SDK package metrics.set_meter_provider(MeterProvider()) -# Meter is responsible for creating and recording metrics meter = metrics.get_meter(__name__) -# exporter to export metrics to the console exporter = ConsoleMetricsExporter() -# controller collects metrics created from meter and exports it via the -# exporter every interval controller = PushController(meter=meter, exporter=exporter, interval=5) -# Example to show how to record using the meter -counter = meter.create_metric( +requests_counter = meter.create_metric( name="requests", description="number of requests", unit="1", @@ -43,7 +38,16 @@ label_keys=("environment",), ) -counter2 = meter.create_metric( +requests_size = meter.create_metric( + name="requests_size", + description="size of requests", + unit="1", + value_type=int, + metric_type=Measure, + label_keys=("environment",), +) + +clicks_counter = meter.create_metric( name="clicks", description="number of clicks", unit="1", @@ -52,36 +56,27 @@ label_keys=("environment",), ) -# Labelsets are used to identify key-values that are associated with a specific -# metric that you want to record. These are useful for pre-aggregation and can -# be used to store custom dimensions pertaining to a metric - -# The meter takes a dictionary of key value pairs label_set = meter.get_label_set({"environment": "staging"}) -# Bound instrument usage +print("Updating using direct calling convention...") +# You can record metrics directly using the metric instrument. You pass in a +# labelset that you would like to record for. +requests_counter.add(25, label_set) +time.sleep(5) +print("Updating using a bound instrument...") # You can record metrics with bound metric instruments. Bound metric # instruments are created by passing in a labelset. A bound metric instrument # is essentially metric data that corresponds to a specific set of labels. # Therefore, getting a bound metric instrument using the same set of labels # will yield the same bound metric instrument. -bound_counter = counter.bind(label_set) -for i in range(1000): - bound_counter.add(i) - -# You can release the bound instrument we you are done -bound_counter.release() - -# Direct metric usage -# You can record metrics directly using the metric instrument. You pass in a -# labelset that you would like to record for. -counter.add(25, label_set) +bound_requests_counter = requests_counter.bind(label_set) +bound_requests_counter.add(100) +time.sleep(5) -# Record batch usage +print("Updating using batch calling convention...") # You can record metrics in a batch by passing in a labelset and a sequence of # (metric, value) pairs. The value would be recorded for each metric using the # specified labelset for each. -meter.record_batch(label_set, [(counter, 50), (counter2, 70)]) - -time.sleep(10) +meter.record_batch(label_set, ((requests_counter, 50), (clicks_counter, 70))) +time.sleep(5) diff --git a/docs/examples/metrics/observer_example.py b/docs/examples/basic_meter/observer.py similarity index 94% rename from docs/examples/metrics/observer_example.py rename to docs/examples/basic_meter/observer.py index 563d503c3e..2b459f25be 100644 --- a/docs/examples/metrics/observer_example.py +++ b/docs/examples/basic_meter/observer.py @@ -26,14 +26,9 @@ # Configure a stateful batcher batcher = UngroupedBatcher(stateful=True) - metrics.set_meter_provider(MeterProvider()) meter = metrics.get_meter(__name__) - -# Exporter to export metrics to the console exporter = ConsoleMetricsExporter() - -# Configure a push controller controller = PushController(meter=meter, exporter=exporter, interval=2) @@ -69,4 +64,4 @@ def get_ram_usage_callback(observer): label_keys=(), ) -input("Press a key to finish...\n") +input("Metrics will be printed soon. Press a key to finish...\n") diff --git a/docs/examples/basic_tracer/README.rst b/docs/examples/basic_tracer/README.rst index 2cc2d0c6a6..47b16074c5 100644 --- a/docs/examples/basic_tracer/README.rst +++ b/docs/examples/basic_tracer/README.rst @@ -2,24 +2,25 @@ Basic Tracer ============ This example shows how to use OpenTelemetry to instrument a Python application - e.g. a batch job. -It supports exporting spans either to the console or to Jaeger_. -The source files required to run this example are available :scm_web:`here `. +The source files of this example are available :scm_web:`here `. +Installation +------------ -Run the application -------------------- +.. code-block:: sh -Console -******* + pip install opentelemetry-api + pip install opentelemetry-sdk -* Run the sample +Run the Example +--------------- .. code-block:: sh - $ python tracer.py + python tracer.py -The output will be displayed at the console +The output will be displayed in the console: :: @@ -29,48 +30,10 @@ The output will be displayed at the console Span(name="foo", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1d5d87441ec2f410, trace_state={}), kind=SpanKind.INTERNAL, parent=None, start_time=2019-11-07T21:26:45.934369Z, end_time=2019-11-07T21:26:45.934580Z) -Jaeger -****** - -Setup `Jaeger Tracing `_. - -* Run the sample - -.. code-block:: sh - - $ pip install opentelemetry-ext-jaeger - $ EXPORTER=jaeger python tracer.py - - -The traces should be available in the Jaeger UI at ``_ - - -Collector -********* - -* Start Collector - -.. code-block:: sh - - $ pip install docker-compose - $ cd docker - $ docker-compose up - -* Run the sample - -.. code-block:: sh - - $ pip install opentelemetry-ext-otcollector - $ EXPORTER=collector python tracer.py - - -Collector is configured to export to Jaeger, follow Jaeger UI instructions to find the traces. - Useful links ------------ -- For more information on OpenTelemetry, visit OpenTelemetry_. -- For more information on tracing in Python, visit Jaeger_. +- OpenTelemetry_ +- :doc:`../../api/trace` -.. _Jaeger: https://www.jaegertracing.io/ .. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/ \ No newline at end of file diff --git a/docs/examples/basic_tracer/tracer.py b/docs/examples/basic_tracer/tracer.py index 8982e5cd7b..51b2e69b12 100755 --- a/docs/examples/basic_tracer/tracer.py +++ b/docs/examples/basic_tracer/tracer.py @@ -23,35 +23,17 @@ ConsoleSpanExporter, ) -if os.getenv("EXPORTER") == "jaeger": - from opentelemetry.ext.jaeger import JaegerSpanExporter - - print("Using JaegerSpanExporter") - exporter = JaegerSpanExporter( - service_name="basic-service", - agent_host_name="localhost", - agent_port=6831, - ) -elif os.getenv("EXPORTER") == "collector": - from opentelemetry.ext.otcollector.trace_exporter import ( - CollectorSpanExporter, - ) - - print("Using CollectorSpanExporter") - exporter = CollectorSpanExporter( - service_name="basic-service", endpoint="localhost:55678" - ) -else: - print("Using ConsoleSpanExporter") - exporter = ConsoleSpanExporter() - +# The preferred tracer implementation must be set, as the opentelemetry-api +# defines the interface with a no-op implementation. trace.set_tracer_provider(TracerProvider()) + # We tell OpenTelemetry who it is that is creating spans. In this case, we have # no real name (no setup.py), so we make one up. If we had a version, we would # also specify it here. tracer = trace.get_tracer(__name__) # SpanExporter receives the spans and send them to the target location. +exporter = ConsoleSpanExporter() span_processor = BatchExportSpanProcessor(exporter) trace.get_tracer_provider().add_span_processor(span_processor) diff --git a/docs/examples/http/README.rst b/docs/examples/http/README.rst index 2d7ef887d7..c462d9f092 100644 --- a/docs/examples/http/README.rst +++ b/docs/examples/http/README.rst @@ -1,53 +1,50 @@ -HTTP Example -============ +HTTP Integration Example +======================== This example shows how to use -`OpenTelemetryMiddleware `_ -and `requests `_ integrations to instrument a client and a server in Python. -It supports exporting spans either to the console or to Jaeger_. +:doc:`WSGI Middleware <../../ext/wsgi/wsgi>` +and :doc:`requests <../../ext/http_requests/http_requests>` integrations to +instrument an HTTP client and server in Python. The source files required to run this example are available :scm_web:`here `. - Installation ------------ .. code-block:: sh - $ pip install opentelemetry-api - $ pip install opentelemetry-sdk - $ pip install opentelemetry-ext-wsgi - $ pip install opentelemetry-ext-http-requests - + pip install opentelemetry-api + pip install opentelemetry-sdk + pip install opentelemetry-ext-wsgi + pip install opentelemetry-ext-http-requests + pip install flask -Run the application -------------------- -Console -******* +Run the Example +--------------- * Run the server .. code-block:: sh - $ python server.py + python server.py * Run the client from a different terminal .. code-block:: sh - $ python tracer_client.py + python client.py -The output will be displayed at the console on the client side +The output will be displayed in the console on the client side: :: Span(name="/", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x3703fd889dcdeb2b, trace_state={}), kind=SpanKind.CLIENT, parent=None, start_time=2019-11-07T21:52:59.591634Z, end_time=2019-11-07T21:53:00.386014Z) -And on the server +And on the server: :: @@ -57,31 +54,12 @@ And on the server Span(name="/", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x36050ac596949bc1, trace_state={}), kind=SpanKind.SERVER, parent=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x3703fd889dcdeb2b, trace_state={}), start_time=2019-11-07T21:52:59.600816Z, end_time=2019-11-07T21:53:00.385322Z) -Jaeger -****** - -Setup `Jaeger Tracing `_. - -* Run the server - -.. code-block:: sh - - $ pip install opentelemetry-ext-jaeger - $ EXPORTER=jaeger python server.py - -* Run the client from a different terminal - -.. code-block:: sh - - $ EXPORTER=jaeger python tracer_client.py - -The traces should be available in the Jaeger UI at ``_ - Useful links ------------ -- For more information on OpenTelemetry, visit OpenTelemetry_. -- For more information on tracing in Python, visit Jaeger_. +- OpenTelemetry_ +- :doc:`../../api/trace` +- :doc:`../../ext/wsgi/wsgi` +- :doc:`../../ext/http_requests/http_requests` -.. _Jaeger: https://www.jaegertracing.io/ .. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/ \ No newline at end of file diff --git a/docs/examples/http/tracer_client.py b/docs/examples/http/client.py similarity index 79% rename from docs/examples/http/tracer_client.py rename to docs/examples/http/client.py index 0e83c5c53f..7c5aaa4130 100755 --- a/docs/examples/http/tracer_client.py +++ b/docs/examples/http/client.py @@ -26,21 +26,12 @@ ConsoleSpanExporter, ) -if os.getenv("EXPORTER") == "jaeger": - from opentelemetry.ext.jaeger import JaegerSpanExporter - - exporter = JaegerSpanExporter( - service_name="http-client", - agent_host_name="localhost", - agent_port=6831, - ) -else: - exporter = ConsoleSpanExporter() - +# The preferred tracer implementation must be set, as the opentelemetry-api +# defines the interface with a no-op implementation. trace.set_tracer_provider(TracerProvider()) tracer_provider = trace.get_tracer_provider() -# SpanExporter receives the spans and send them to the target location. +exporter = ConsoleSpanExporter() span_processor = BatchExportSpanProcessor(exporter) tracer_provider.add_span_processor(span_processor) diff --git a/docs/examples/http/server.py b/docs/examples/http/server.py index a665abdd49..ab066e99bf 100755 --- a/docs/examples/http/server.py +++ b/docs/examples/http/server.py @@ -28,20 +28,12 @@ ConsoleSpanExporter, ) -if os.getenv("EXPORTER") == "jaeger": - from opentelemetry.ext.jaeger import JaegerSpanExporter - - exporter = JaegerSpanExporter( - service_name="http-server", - agent_host_name="localhost", - agent_port=6831, - ) -else: - exporter = ConsoleSpanExporter() - +# The preferred tracer implementation must be set, as the opentelemetry-api +# defines the interface with a no-op implementation. +trace.set_tracer_provider(TracerProvider()) tracer = trace.get_tracer(__name__) -# SpanExporter receives the spans and send them to the target location. +exporter = ConsoleSpanExporter() span_processor = BatchExportSpanProcessor(exporter) trace.set_tracer_provider(TracerProvider()) trace.get_tracer_provider().add_span_processor(span_processor) diff --git a/docs/examples/http/tests/test_http.py b/docs/examples/http/tests/test_http.py index 0ae81fe7de..dec0ce5f38 100644 --- a/docs/examples/http/tests/test_http.py +++ b/docs/examples/http/tests/test_http.py @@ -28,7 +28,7 @@ def setup_class(cls): def test_http(self): dirpath = os.path.dirname(os.path.realpath(__file__)) - test_script = "{}/../tracer_client.py".format(dirpath) + test_script = "{}/../client.py".format(dirpath) output = subprocess.check_output( (sys.executable, test_script) ).decode() diff --git a/docs/examples/jaeger_exporter/README.rst b/docs/examples/jaeger_exporter/README.rst new file mode 100644 index 0000000000..d4e20bad3f --- /dev/null +++ b/docs/examples/jaeger_exporter/README.rst @@ -0,0 +1,46 @@ +Jaeger Exporter Example +======================= + +This example shows how to use OpenTelemetry to send tracing data to Jaeger. + +The source files of this example are available :scm_web:`here `. + +Installation +------------ + +.. code-block:: sh + + pip install opentelemetry-api + pip install opentelemetry-sdk + pip install opentelemetry-ext-jaeger + +Run the Example +--------------- + +* Start Jaeger + +.. code-block:: sh + + docker run --rm \ + -p 6831:6831/udp \ + -p 6832:6832/udp \ + -p 16686:16686 \ + jaegertracing/all-in-one:1.13 \ + --log-level=debug + +* Run the example + +.. code-block:: sh + + python jaeger_exporter.py + +The traces will be available at http://localhost:16686/. + +Useful links +------------ + +- OpenTelemetry_ +- :doc:`../../api/trace` +- :doc:`../../ext/jaeger/jaeger` + +.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/ \ No newline at end of file diff --git a/docs/examples/jaeger_exporter/jaeger_exporter.py b/docs/examples/jaeger_exporter/jaeger_exporter.py new file mode 100644 index 0000000000..f8914c353a --- /dev/null +++ b/docs/examples/jaeger_exporter/jaeger_exporter.py @@ -0,0 +1,46 @@ +#!/usr/bin/env python3 +# +# Copyright 2020, OpenTelemetry Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import os + +from opentelemetry import trace +from opentelemetry.ext.jaeger import JaegerSpanExporter +from opentelemetry.sdk.trace import TracerProvider +from opentelemetry.sdk.trace.export import BatchExportSpanProcessor + +trace.set_tracer_provider(TracerProvider()) +tracer = trace.get_tracer(__name__) + +exporter = JaegerSpanExporter( + service_name="my-helloworld-service", + # configure agent + agent_host_name="localhost", + agent_port=6831, + # optional: configure also collector + # collector_host_name="localhost", + # collector_port=14268, + # collector_endpoint="/api/traces?format=jaeger.thrift", + # username=xxxx, # optional + # password=xxxx, # optional +) + +span_processor = BatchExportSpanProcessor(exporter) +trace.get_tracer_provider().add_span_processor(span_processor) + +with tracer.start_as_current_span("foo"): + with tracer.start_as_current_span("bar"): + with tracer.start_as_current_span("baz"): + print("Hello world from OpenTelemetry Python!") diff --git a/docs/examples/opentracing/README.rst b/docs/examples/opentracing/README.rst index 0305da9955..06c767b199 100644 --- a/docs/examples/opentracing/README.rst +++ b/docs/examples/opentracing/README.rst @@ -1,8 +1,8 @@ OpenTracing Shim Example ========================== -This example shows how to use the `opentelemetry-ext-opentracing-shim -package `_ +This example shows how to use the :doc:`opentelemetry-ext-opentracing-shim +package <../../ext/opentracing_shim/opentracing_shim>` to interact with libraries instrumented with `opentracing-python `_. @@ -21,7 +21,16 @@ Installation Jaeger ****** -Setup `Jaeger Tracing `_. +Start Jaeger + +.. code-block:: sh + + docker run --rm \ + -p 6831:6831/udp \ + -p 6832:6832/udp \ + -p 16686:16686 \ + jaegertracing/all-in-one:1.13 \ + --log-level=debug Redis ***** @@ -32,30 +41,30 @@ Make sure that the Redis server is running by executing this: .. code-block:: sh - $ redis-server + redis-server Python Dependencies ******************* -Install the Python dependencies in :scm_raw_web:`requirements.txt ` +Install the Python dependencies in :scm_raw_web:`requirements.txt ` .. code-block:: sh - $ pip install -r requirements.txt + pip install -r requirements.txt Alternatively, you can install the Python dependencies separately: .. code-block:: sh - $ pip install \ - opentelemetry-api \ - opentelemetry-sdk \ - opentelemetry-ext-jaeger \ - opentelemetry-opentracing-shim \ - redis \ - redis_opentracing + pip install \ + opentelemetry-api \ + opentelemetry-sdk \ + opentelemetry-ext-jaeger \ + opentelemetry-opentracing-shim \ + redis \ + redis_opentracing Run the Application @@ -69,7 +78,7 @@ To run the script: .. code-block:: sh - $ python main.py + python main.py After running, you can view the generated trace in the Jaeger UI. @@ -90,8 +99,7 @@ from both tracing systems appear in the exported trace. Useful links ------------ -- For more information on OpenTelemetry, visit OpenTelemetry_. -- For more information on tracing in Python, visit Jaeger_. +- OpenTelemetry_ +- :doc:`../../ext/opentracing_shim/opentracing_shim` -.. _Jaeger: https://www.jaegertracing.io/ .. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/ diff --git a/docs/examples/opentracing/images/jaeger-span-expanded.png b/docs/examples/opentracing/images/jaeger-span-expanded.png deleted file mode 100644 index 6da4b4b014..0000000000 Binary files a/docs/examples/opentracing/images/jaeger-span-expanded.png and /dev/null differ diff --git a/docs/examples/opentracing/images/jaeger-trace-full.png b/docs/examples/opentracing/images/jaeger-trace-full.png deleted file mode 100644 index c28255bd13..0000000000 Binary files a/docs/examples/opentracing/images/jaeger-trace-full.png and /dev/null differ diff --git a/docs/examples/otcollector-metrics/README.rst b/docs/examples/otcollector-metrics/README.rst new file mode 100644 index 0000000000..c52127cbd2 --- /dev/null +++ b/docs/examples/otcollector-metrics/README.rst @@ -0,0 +1,51 @@ +OT Collector Metrics Exporter Example +===================================== + +This example shows how to export metrics to the OT collector. + +The source files of this example are available :scm_web:`here `. + +Installation +------------ + +.. code-block:: sh + + pip install opentelemetry-api + pip install opentelemetry-sdk + pip install opentelemetry-ext-otcollector + +Run the Example +--------------- + +Before running the example, it's necessary to run the OpenTelemetry collector +and Prometheus. The :scm_web:`docker ` +folder contains the a docker-compose template with the configuration of those +services. + +.. code-block:: sh + + pip install docker-compose + cd docker + docker-compose up + + +Now, the example can be executed: + +.. code-block:: sh + + python collector.py + + +The metrics are available in the Prometheus dashboard at http://localhost:9090/graph, +look for the "requests" metric on the list. + +Useful links +------------ + +- OpenTelemetry_ +- OTCollector_ +- :doc:`../../api/metrics` +- :doc:`../../ext/otcollector/otcollector` + +.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/ +.. _OTCollector: https://github.com/open-telemetry/opentelemetry-collector \ No newline at end of file diff --git a/examples/metrics/collector.py b/docs/examples/otcollector-metrics/collector.py similarity index 60% rename from examples/metrics/collector.py rename to docs/examples/otcollector-metrics/collector.py index 929cfd43f3..5e1f401e38 100644 --- a/examples/metrics/collector.py +++ b/docs/examples/otcollector-metrics/collector.py @@ -13,8 +13,7 @@ # limitations under the License. # """ -This module serves as an example for a simple application using metrics -exporting to Collector +This example shows how to export metrics to the OT collector. """ from opentelemetry import metrics @@ -24,30 +23,25 @@ from opentelemetry.sdk.metrics import Counter, MeterProvider from opentelemetry.sdk.metrics.export.controller import PushController -# Meter is responsible for creating and recording metrics -metrics.set_meter_provider(MeterProvider()) -meter = metrics.get_meter(__name__) -# exporter to export metrics to OT Collector exporter = CollectorMetricsExporter( service_name="basic-service", endpoint="localhost:55678" ) -# controller collects metrics created from meter and exports it via the -# exporter every interval + +metrics.set_meter_provider(MeterProvider()) +meter = metrics.get_meter(__name__) controller = PushController(meter, exporter, 5) -counter = meter.create_metric( - "requests", - "number of requests", - "requests", - int, - Counter, - ("environment",), +requests_counter = meter.create_metric( + name="requests", + description="number of requests", + unit="1", + value_type=int, + metric_type=Counter, + label_keys=("environment",), ) -# Labelsets are used to identify key-values that are associated with a specific -# metric that you want to record. These are useful for pre-aggregation and can -# be used to store custom dimensions pertaining to a metric -label_set = meter.get_label_set({"environment": "staging"}) +staging_label_set = meter.get_label_set({"environment": "staging"}) +requests_counter.add(25, staging_label_set) -counter.add(25, label_set) +print("Metrics are available now at http://localhost:9090/graph") input("Press any key to exit...") diff --git a/examples/metrics/docker/collector-config.yaml b/docs/examples/otcollector-metrics/docker/collector-config.yaml similarity index 100% rename from examples/metrics/docker/collector-config.yaml rename to docs/examples/otcollector-metrics/docker/collector-config.yaml diff --git a/examples/metrics/docker/docker-compose.yaml b/docs/examples/otcollector-metrics/docker/docker-compose.yaml similarity index 100% rename from examples/metrics/docker/docker-compose.yaml rename to docs/examples/otcollector-metrics/docker/docker-compose.yaml diff --git a/examples/metrics/docker/prometheus.yaml b/docs/examples/otcollector-metrics/docker/prometheus.yaml similarity index 100% rename from examples/metrics/docker/prometheus.yaml rename to docs/examples/otcollector-metrics/docker/prometheus.yaml diff --git a/docs/examples/otcollector-tracer/README.rst b/docs/examples/otcollector-tracer/README.rst new file mode 100644 index 0000000000..d82803df40 --- /dev/null +++ b/docs/examples/otcollector-tracer/README.rst @@ -0,0 +1,50 @@ +OT Collector Tracer Exporter Example +==================================== + +This example shows how to export traces to the OT collector. + +The source files of this example are available :scm_web:`here `. + +Installation +------------ + +.. code-block:: sh + + pip install opentelemetry-api + pip install opentelemetry-sdk + pip install opentelemetry-ext-otcollector + +Run the Example +--------------- + +Before running the example, it's necessary to run the OpenTelemetry collector +and Jaeger. The :scm_web:`docker ` +folder contains the a docker-compose template with the configuration of those +services. + +.. code-block:: sh + + pip install docker-compose + cd docker + docker-compose up + + +Now, the example can be executed: + +.. code-block:: sh + + python collector.py + + +The traces are available in the Jaeger UI at http://localhost:16686/. + +Useful links +------------ + +- OpenTelemetry_ +- OTCollector_ +- :doc:`../../api/trace` +- :doc:`../../ext/otcollector/otcollector` + +.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/ +.. _OTCollector: https://github.com/open-telemetry/opentelemetry-collector \ No newline at end of file diff --git a/docs/examples/otcollector-tracer/collector.py b/docs/examples/otcollector-tracer/collector.py new file mode 100644 index 0000000000..5591effd33 --- /dev/null +++ b/docs/examples/otcollector-tracer/collector.py @@ -0,0 +1,36 @@ +#!/usr/bin/env python3 +# +# Copyright 2020, OpenTelemetry Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import os + +from opentelemetry import trace +from opentelemetry.ext.otcollector.trace_exporter import CollectorSpanExporter +from opentelemetry.sdk.trace import TracerProvider +from opentelemetry.sdk.trace.export import BatchExportSpanProcessor + +exporter = CollectorSpanExporter( + service_name="basic-service", endpoint="localhost:55678" +) + +trace.set_tracer_provider(TracerProvider()) +tracer = trace.get_tracer(__name__) +span_processor = BatchExportSpanProcessor(exporter) + +trace.get_tracer_provider().add_span_processor(span_processor) +with tracer.start_as_current_span("foo"): + with tracer.start_as_current_span("bar"): + with tracer.start_as_current_span("baz"): + print("Hello world from OpenTelemetry Python!") diff --git a/docs/examples/basic_tracer/docker/collector-config.yaml b/docs/examples/otcollector-tracer/docker/collector-config.yaml similarity index 100% rename from docs/examples/basic_tracer/docker/collector-config.yaml rename to docs/examples/otcollector-tracer/docker/collector-config.yaml diff --git a/docs/examples/basic_tracer/docker/docker-compose.yaml b/docs/examples/otcollector-tracer/docker/docker-compose.yaml similarity index 100% rename from docs/examples/basic_tracer/docker/docker-compose.yaml rename to docs/examples/otcollector-tracer/docker/docker-compose.yaml diff --git a/docs/examples/prometheus/README.rst b/docs/examples/prometheus/README.rst new file mode 100644 index 0000000000..963687fdd9 --- /dev/null +++ b/docs/examples/prometheus/README.rst @@ -0,0 +1,34 @@ +Prometheus Metrics Exporter Example +=================================== + +This example shows how to export metrics to Prometheus. + +The source files of this example are available :scm_web:`here `. + +Installation +------------ + +.. code-block:: sh + + pip install opentelemetry-api + pip install opentelemetry-sdk + pip install opentelemetry-ext-prometheus + +Run the Example +--------------- + +.. code-block:: sh + + python prometheus.py + + +The metrics are available at http://localhost:8000/. + +Useful links +------------ + +- OpenTelemetry_ +- :doc:`../../api/metrics` +- :doc:`OpenTelemetry Prometheus Exporter <../../ext/prometheus/prometheus>` + +.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/ diff --git a/docs/examples/metrics/prometheus.py b/docs/examples/prometheus/prometheus.py similarity index 53% rename from docs/examples/metrics/prometheus.py rename to docs/examples/prometheus/prometheus.py index c3754c89a2..8806d00780 100644 --- a/docs/examples/metrics/prometheus.py +++ b/docs/examples/prometheus/prometheus.py @@ -13,43 +13,36 @@ # limitations under the License. # """ -This module serves as an example for a simple application using metrics -Examples show how to recording affects the collection of metrics to be exported +This example shows how to export metrics to Prometheus. """ from prometheus_client import start_http_server from opentelemetry import metrics from opentelemetry.ext.prometheus import PrometheusMetricsExporter -from opentelemetry.sdk.metrics import Counter, MeterProvider +from opentelemetry.sdk.metrics import Counter, Measure, MeterProvider from opentelemetry.sdk.metrics.export.controller import PushController # Start Prometheus client start_http_server(port=8000, addr="localhost") -# Meter is responsible for creating and recording metrics metrics.set_meter_provider(MeterProvider()) meter = metrics.get_meter(__name__) -# exporter to export metrics to Prometheus -prefix = "MyAppPrefix" -exporter = PrometheusMetricsExporter(prefix) -# controller collects metrics created from meter and exports it via the -# exporter every interval + +exporter = PrometheusMetricsExporter(prefix="MyAppPrefix") controller = PushController(meter, exporter, 5) -counter = meter.create_metric( - "requests", - "number of requests", - "requests", - int, - Counter, - ("environment",), +requests_counter = meter.create_metric( + name="requests", + description="number of requests", + unit="1", + value_type=int, + metric_type=Counter, + label_keys=("environment",), ) -# Labelsets are used to identify key-values that are associated with a specific -# metric that you want to record. These are useful for pre-aggregation and can -# be used to store custom dimensions pertaining to a metric -label_set = meter.get_label_set({"environment": "staging"}) +staging_label_set = meter.get_label_set({"environment": "staging"}) +requests_counter.add(25, staging_label_set) -counter.add(25, label_set) +print("Metrics are available now at http://localhost:8000/") input("Press any key to exit...") diff --git a/docs/ext/dbapi/dbapi.rst b/docs/ext/dbapi/dbapi.rst index dbe6dbbeab..d87d968b4b 100644 --- a/docs/ext/dbapi/dbapi.rst +++ b/docs/ext/dbapi/dbapi.rst @@ -1,8 +1,5 @@ -.. include:: ../../../ext/opentelemetry-ext-dbapi/README.rst - - -Module contents ---------------- +OpenTelemetry Database API Integration +====================================== .. automodule:: opentelemetry.ext.dbapi :members: diff --git a/docs/ext/flask/flask.rst b/docs/ext/flask/flask.rst index e65323cc81..2fc19de3ec 100644 --- a/docs/ext/flask/flask.rst +++ b/docs/ext/flask/flask.rst @@ -1,8 +1,5 @@ -.. include:: ../../../ext/opentelemetry-ext-flask/README.rst - - -Module contents ---------------- +OpenTelemetry Flask Integration +=============================== .. automodule:: opentelemetry.ext.flask :members: diff --git a/docs/ext/http_requests/http_requests.rst b/docs/ext/http_requests/http_requests.rst index 779be3e033..9cc09de547 100644 --- a/docs/ext/http_requests/http_requests.rst +++ b/docs/ext/http_requests/http_requests.rst @@ -1,7 +1,5 @@ -.. include:: ../../../ext/opentelemetry-ext-http-requests/README.rst - -Module contents ---------------- +OpenTelemetry requests Integration +================================== .. automodule:: opentelemetry.ext.http_requests :members: diff --git a/docs/ext/jaeger/jaeger.rst b/docs/ext/jaeger/jaeger.rst index 70b9c04205..d7b93a6f10 100644 --- a/docs/ext/jaeger/jaeger.rst +++ b/docs/ext/jaeger/jaeger.rst @@ -1,13 +1,12 @@ -.. include:: ../../../ext/opentelemetry-ext-jaeger/README.rst - -Module contents ---------------- +Opentelemetry Jaeger Exporter +============================= .. automodule:: opentelemetry.ext.jaeger :members: :undoc-members: :show-inheritance: + Submodules ---------- diff --git a/docs/ext/mysql/mysql.rst b/docs/ext/mysql/mysql.rst index e2c01371cd..4fd4749731 100644 --- a/docs/ext/mysql/mysql.rst +++ b/docs/ext/mysql/mysql.rst @@ -1,8 +1,5 @@ -.. include:: ../../../ext/opentelemetry-ext-mysql/README.rst - - -Module contents ---------------- +OpenTelemetry MySQL Integration +=============================== .. automodule:: opentelemetry.ext.mysql :members: diff --git a/docs/ext/otcollector/otcollector.rst b/docs/ext/otcollector/otcollector.rst index c940bfacaa..286aed6c08 100644 --- a/docs/ext/otcollector/otcollector.rst +++ b/docs/ext/otcollector/otcollector.rst @@ -1,8 +1,5 @@ -.. include:: ../../../ext/opentelemetry-ext-otcollector/README.rst - - -Module contents ---------------- +OpenTelemetry Collector Exporter +================================ .. automodule:: opentelemetry.ext.otcollector :members: diff --git a/docs/ext/prometheus/prometheus.rst b/docs/ext/prometheus/prometheus.rst index 7f331cb6da..9ca7754af9 100644 --- a/docs/ext/prometheus/prometheus.rst +++ b/docs/ext/prometheus/prometheus.rst @@ -1,8 +1,5 @@ -.. include:: ../../../ext/opentelemetry-ext-prometheus/README.rst - - -Module contents ---------------- +OpenTelemetry Prometheus Exporter +================================= .. automodule:: opentelemetry.ext.prometheus :members: diff --git a/docs/ext/psycopg2/psycopg2.rst b/docs/ext/psycopg2/psycopg2.rst index 89cebce345..c9c0037546 100644 --- a/docs/ext/psycopg2/psycopg2.rst +++ b/docs/ext/psycopg2/psycopg2.rst @@ -1,8 +1,5 @@ -.. include:: ../../../ext/opentelemetry-ext-psycopg2/README.rst - - -Module contents ---------------- +OpenTelemetry Psycopg Integration +================================= .. automodule:: opentelemetry.ext.psycopg2 :members: diff --git a/docs/ext/pymongo/pymongo.rst b/docs/ext/pymongo/pymongo.rst index 848c0dba25..e75f4f4168 100644 --- a/docs/ext/pymongo/pymongo.rst +++ b/docs/ext/pymongo/pymongo.rst @@ -1,7 +1,5 @@ -.. include:: ../../../ext/opentelemetry-ext-pymongo/README.rst - -Module contents ---------------- +OpenTelemetry pymongo Integration +================================= .. automodule:: opentelemetry.ext.pymongo :members: diff --git a/docs/ext/wsgi/wsgi.rst b/docs/ext/wsgi/wsgi.rst index be8194bdd6..af2bd4dd36 100644 --- a/docs/ext/wsgi/wsgi.rst +++ b/docs/ext/wsgi/wsgi.rst @@ -1,8 +1,5 @@ -.. include:: ../../../ext/opentelemetry-ext-wsgi/README.rst - - -Module contents ---------------- +OpenTelemetry WSGI Middleware +============================= .. automodule:: opentelemetry.ext.wsgi :members: diff --git a/docs/index.rst b/docs/index.rst index bc09b5a475..fd60e72f03 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -71,7 +71,7 @@ install sdk/sdk .. toctree:: - :maxdepth: 1 + :maxdepth: 2 :caption: OpenTelemetry Integrations :name: integrations :glob: diff --git a/ext/opentelemetry-ext-dbapi/README.rst b/ext/opentelemetry-ext-dbapi/README.rst index b3f91511c3..1ff464cb48 100644 --- a/ext/opentelemetry-ext-dbapi/README.rst +++ b/ext/opentelemetry-ext-dbapi/README.rst @@ -1,31 +1,21 @@ OpenTelemetry Database API integration ====================================== -The trace integration with Database API supports libraries following the specification. +|pypi| -.. PEP 249 -- Python Database API Specification v2.0: https://www.python.org/dev/peps/pep-0249/ +.. |pypi| image:: https://badge.fury.io/py/opentelemetry-ext-dbapi.svg + :target: https://pypi.org/project/opentelemetry-ext-dbapi/ -Usage ------ +Installation +------------ -.. code-block:: python +:: - import mysql.connector - import pyodbc - - from opentelemetry.ext.dbapi import trace_integration - from opentelemetry.sdk.trace import TracerProvider - from opentelemetry.trace import tracer_provider - - trace.set_tracer_provider(TracerProvider()) - tracer = trace.get_tracer(__name__) - # Ex: mysql.connector - trace_integration(tracer_provider(), mysql.connector, "connect", "mysql", "sql") - # Ex: pyodbc - trace_integration(tracer_provider(), pyodbc, "Connection", "odbc", "sql") + pip install opentelemetry-ext-dbapi References ---------- +* `OpenTelemetry Database API integration `_ * `OpenTelemetry Project `_ diff --git a/ext/opentelemetry-ext-dbapi/src/opentelemetry/ext/dbapi/__init__.py b/ext/opentelemetry-ext-dbapi/src/opentelemetry/ext/dbapi/__init__.py index 88e9d3a0b1..7b015dd2fb 100644 --- a/ext/opentelemetry-ext-dbapi/src/opentelemetry/ext/dbapi/__init__.py +++ b/ext/opentelemetry-ext-dbapi/src/opentelemetry/ext/dbapi/__init__.py @@ -13,9 +13,28 @@ # limitations under the License. """ -The opentelemetry-ext-dbapi package allows tracing queries made by the -ibraries following Ptyhon Database API specification: -https://www.python.org/dev/peps/pep-0249/ +The trace integration with Database API supports libraries following the +`Python Database API Specification v2.0. `_ + +Usage +----- + +.. code-block:: python + + import mysql.connector + import pyodbc + from opentelemetry.trace import tracer_provider + from opentelemetry.ext.dbapi import trace_integration + + trace.set_tracer_provider(TracerProvider()) + tracer = trace.get_tracer(__name__) + # Ex: mysql.connector + trace_integration(tracer_provider(), mysql.connector, "connect", "mysql", "sql") + # Ex: pyodbc + trace_integration(tracer_provider(), pyodbc, "Connection", "odbc", "sql") + +API +--- """ import functools @@ -40,6 +59,7 @@ def trace_integration( ): """Integrate with DB API library. https://www.python.org/dev/peps/pep-0249/ + Args: tracer: The :class:`Tracer` to use. connect_module: Module name where connect method is available. diff --git a/ext/opentelemetry-ext-flask/README.rst b/ext/opentelemetry-ext-flask/README.rst index 182f0960b2..135b2c398c 100644 --- a/ext/opentelemetry-ext-flask/README.rst +++ b/ext/opentelemetry-ext-flask/README.rst @@ -1,35 +1,24 @@ -OpenTelemetry Flask tracing +OpenTelemetry Flask Tracing =========================== -This library builds on the OpenTelemetry WSGI middleware to track web requests -in Flask applications. In addition to opentelemetry-ext-wsgi, it supports -flask-specific features such as: - -* The Flask endpoint name is used as the Span name. -* The ``http.route`` Span attribute is set so that one can see which URL rule - matched a request. +|pypi| -Usage ------ +.. |pypi| image:: https://badge.fury.io/py/opentelemetry-ext-flask.svg + :target: https://pypi.org/project/opentelemetry-ext-flask/ -.. code-block:: python - - from flask import Flask - from opentelemetry.ext.flask import instrument_app +This library builds on the OpenTelemetry WSGI middleware to track web requests +in Flask applications. - app = Flask(__name__) - instrument_app(app) # This is where the magic happens. ✨ +Installation +------------ - @app.route("/") - def hello(): - return "Hello!" +:: - if __name__ == "__main__": - app.run(debug=True) + pip install opentelemetry-ext-flask References ---------- +* `OpenTelemetry Flask Tracing `_ * `OpenTelemetry Project `_ -* `OpenTelemetry WSGI extension `_ diff --git a/ext/opentelemetry-ext-flask/src/opentelemetry/ext/flask/__init__.py b/ext/opentelemetry-ext-flask/src/opentelemetry/ext/flask/__init__.py index b30b42d3fd..11c027ecbc 100644 --- a/ext/opentelemetry-ext-flask/src/opentelemetry/ext/flask/__init__.py +++ b/ext/opentelemetry-ext-flask/src/opentelemetry/ext/flask/__init__.py @@ -1,6 +1,37 @@ # Note: This package is not named "flask" because of # https://github.com/PyCQA/pylint/issues/2648 +""" +This library builds on the OpenTelemetry WSGI middleware to track web requests +in Flask applications. In addition to opentelemetry-ext-wsgi, it supports +flask-specific features such as: + +* The Flask endpoint name is used as the Span name. +* The ``http.route`` Span attribute is set so that one can see which URL rule + matched a request. + +Usage +----- + +.. code-block:: python + + from flask import Flask + from opentelemetry.ext.flask import instrument_app + + app = Flask(__name__) + instrument_app(app) # This is where the magic happens. ✨ + + @app.route("/") + def hello(): + return "Hello!" + + if __name__ == "__main__": + app.run(debug=True) + +API +--- +""" + import logging from flask import request as flask_request diff --git a/ext/opentelemetry-ext-http-requests/README.rst b/ext/opentelemetry-ext-http-requests/README.rst index a4b79005b5..0b05b2643f 100644 --- a/ext/opentelemetry-ext-http-requests/README.rst +++ b/ext/opentelemetry-ext-http-requests/README.rst @@ -1,4 +1,4 @@ -OpenTelemetry requests integration +OpenTelemetry requests Integration ================================== |pypi| @@ -6,7 +6,8 @@ OpenTelemetry requests integration .. |pypi| image:: https://badge.fury.io/py/opentelemetry-ext-http-requests.svg :target: https://pypi.org/project/opentelemetry-ext-http-requests/ -This library allows tracing HTTP requests made by the popular `requests `_ library. +This library allows tracing HTTP requests made by the +`requests `_ library. Installation ------------ @@ -15,28 +16,8 @@ Installation pip install opentelemetry-ext-http-requests -Usage ------ - -.. code-block:: python - - import requests - import opentelemetry.ext.http_requests - from opentelemetry.trace import tracer_provider - - opentelemetry.ext.http_requests.enable(tracer_provider()) - response = requests.get(url='https://www.example.org/') - -Limitations ------------ - -Note that calls that do not use the higher-level APIs but use -:code:`requests.sessions.Session.send` (or an alias thereof) directly, are -currently not traced. If you find any other way to trigger an untraced HTTP -request, please report it via a GitHub issue with :code:`[requests: untraced -API]` in the title. - References ---------- +* `OpenTelemetry requests Integration `_ * `OpenTelemetry Project `_ diff --git a/ext/opentelemetry-ext-http-requests/src/opentelemetry/ext/http_requests/__init__.py b/ext/opentelemetry-ext-http-requests/src/opentelemetry/ext/http_requests/__init__.py index 8e4b3e2cc0..517069ad0d 100644 --- a/ext/opentelemetry-ext-http-requests/src/opentelemetry/ext/http_requests/__init__.py +++ b/ext/opentelemetry-ext-http-requests/src/opentelemetry/ext/http_requests/__init__.py @@ -13,8 +13,32 @@ # limitations under the License. """ -The opentelemetry-ext-requests package allows tracing HTTP requests made by the -popular requests library. +This library allows tracing HTTP requests made by the +`requests `_ library. + +Usage +----- + +.. code-block:: python + + import requests + import opentelemetry.ext.http_requests + from opentelemetry.trace import tracer_provider + + opentelemetry.ext.http_requests.enable(tracer_provider()) + response = requests.get(url='https://www.example.org/') + +Limitations +----------- + +Note that calls that do not use the higher-level APIs but use +:code:`requests.sessions.Session.send` (or an alias thereof) directly, are +currently not traced. If you find any other way to trigger an untraced HTTP +request, please report it via a GitHub issue with :code:`[requests: untraced +API]` in the title. + +API +--- """ import functools diff --git a/ext/opentelemetry-ext-jaeger/README.rst b/ext/opentelemetry-ext-jaeger/README.rst index 23be60ac68..caa3afa932 100644 --- a/ext/opentelemetry-ext-jaeger/README.rst +++ b/ext/opentelemetry-ext-jaeger/README.rst @@ -13,58 +13,16 @@ Installation :: - pip install opentelemetry-ext-jaeger - - -Usage ------ - -The **OpenTelemetry Jaeger Exporter** allows to export `OpenTelemetry`_ traces to `Jaeger`_. -This exporter always send traces to the configured agent using Thrift compact protocol over UDP. -An optional collector can be configured, in this case Thrift binary protocol over HTTP is used. -gRPC is still not supported by this implementation. + pip install opentelemetry-ext-jaeger .. _Jaeger: https://www.jaegertracing.io/ .. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/ -.. code:: python - - from opentelemetry import trace - from opentelemetry.ext import jaeger - from opentelemetry.sdk.trace import TracerProvider - from opentelemetry.sdk.trace.export import BatchExportSpanProcessor - - trace.set_tracer_provider(TracerProvider()) - tracer = trace.get_tracer(__name__) - - # create a JaegerSpanExporter - jaeger_exporter = jaeger.JaegerSpanExporter( - service_name='my-helloworld-service', - # configure agent - agent_host_name='localhost', - agent_port=6831, - # optional: configure also collector - # collector_host_name='localhost', - # collector_port=14268, - # collector_endpoint='/api/traces?format=jaeger.thrift', - # username=xxxx, # optional - # password=xxxx, # optional - ) - - # Create a BatchExportSpanProcessor and add the exporter to it - span_processor = BatchExportSpanProcessor(jaeger_exporter) - - # add to the tracer - trace.tracer_provider().add_span_processor(span_processor) - - with tracer.start_as_current_span('foo'): - print('Hello world!') - -The `examples <./examples>`_ folder contains more elaborated examples. References ---------- +* `OpenTelemetry Jaeger Exporter `_ * `Jaeger `_ * `OpenTelemetry Project `_ diff --git a/ext/opentelemetry-ext-jaeger/src/opentelemetry/ext/jaeger/__init__.py b/ext/opentelemetry-ext-jaeger/src/opentelemetry/ext/jaeger/__init__.py index 6679ce6b7e..cee1596711 100644 --- a/ext/opentelemetry-ext-jaeger/src/opentelemetry/ext/jaeger/__init__.py +++ b/ext/opentelemetry-ext-jaeger/src/opentelemetry/ext/jaeger/__init__.py @@ -13,7 +13,53 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Jaeger Span Exporter for OpenTelemetry.""" +""" +The **OpenTelemetry Jaeger Exporter** allows to export `OpenTelemetry`_ traces to `Jaeger`_. +This exporter always send traces to the configured agent using Thrift compact protocol over UDP. +An optional collector can be configured, in this case Thrift binary protocol over HTTP is used. +gRPC is still not supported by this implementation. + +Usage +----- + +.. code:: python + + from opentelemetry import trace + from opentelemetry.ext import jaeger + from opentelemetry.sdk.trace import TracerProvider + from opentelemetry.sdk.trace.export import BatchExportSpanProcessor + + trace.set_tracer_provider(TracerProvider()) + tracer = trace.get_tracer(__name__) + + # create a JaegerSpanExporter + jaeger_exporter = jaeger.JaegerSpanExporter( + service_name='my-helloworld-service', + # configure agent + agent_host_name='localhost', + agent_port=6831, + # optional: configure also collector + # collector_host_name='localhost', + # collector_port=14268, + # collector_endpoint='/api/traces?format=jaeger.thrift', + # username=xxxx, # optional + # password=xxxx, # optional + ) + + # Create a BatchExportSpanProcessor and add the exporter to it + span_processor = BatchExportSpanProcessor(jaeger_exporter) + + # add to the tracer + trace.tracer_provider().add_span_processor(span_processor) + + with tracer.start_as_current_span('foo'): + print('Hello world!') + +API +--- +.. _Jaeger: https://www.jaegertracing.io/ +.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/ +""" import base64 import logging diff --git a/ext/opentelemetry-ext-mysql/README.rst b/ext/opentelemetry-ext-mysql/README.rst index 087d4cb361..0a8577e867 100644 --- a/ext/opentelemetry-ext-mysql/README.rst +++ b/ext/opentelemetry-ext-mysql/README.rst @@ -1,29 +1,25 @@ -OpenTelemetry MySQL integration +OpenTelemetry MySQL Integration =============================== -The integration with MySQL supports the `mysql-connector`_ library and is specified -to ``trace_integration`` using ``'MySQL'``. +|pypi| -.. _mysql-connector: https://pypi.org/project/mysql-connector/ +.. |pypi| image:: https://badge.fury.io/py/opentelemetry-ext-mysql.svg + :target: https://pypi.org/project/opentelemetry-ext-mysql/ -Usage ------ +Integration with MySQL that supports the mysql-connector library and is +specified to trace_integration using 'MySQL'. -.. code:: python - import mysql.connector - from opentelemetry.trace import tracer_provider - from opentelemetry.ext.mysql import trace_integration +Installation +------------ - trace_integration(tracer_provider()) - cnx = mysql.connector.connect(database='MySQL_Database') - cursor = cnx.cursor() - cursor.execute("INSERT INTO test (testField) VALUES (123)" - cursor.close() - cnx.close() +:: + + pip install opentelemetry-ext-mysql References ---------- - +* `OpenTelemetry MySQL Integration `_ * `OpenTelemetry Project `_ + diff --git a/ext/opentelemetry-ext-mysql/src/opentelemetry/ext/mysql/__init__.py b/ext/opentelemetry-ext-mysql/src/opentelemetry/ext/mysql/__init__.py index 9c8c3e9da7..34151431ad 100644 --- a/ext/opentelemetry-ext-mysql/src/opentelemetry/ext/mysql/__init__.py +++ b/ext/opentelemetry-ext-mysql/src/opentelemetry/ext/mysql/__init__.py @@ -13,8 +13,29 @@ # limitations under the License. """ -The opentelemetry-ext-mysql package allows tracing MySQL queries made by the -MySQL Connector/Python library. +The integration with MySQL supports the `mysql-connector`_ library and is specified +to ``trace_integration`` using ``'MySQL'``. + +.. _mysql-connector: https://pypi.org/project/mysql-connector/ + +Usage +----- + +.. code:: python + + import mysql.connector + from opentelemetry.trace import tracer_provider + from opentelemetry.ext.mysql import trace_integration + + trace_integration(tracer_provider()) + cnx = mysql.connector.connect(database='MySQL_Database') + cursor = cnx.cursor() + cursor.execute("INSERT INTO test (testField) VALUES (123)" + cursor.close() + cnx.close() + +API +--- """ import mysql.connector diff --git a/ext/opentelemetry-ext-opentracing-shim/README.rst b/ext/opentelemetry-ext-opentracing-shim/README.rst index 2e81391219..3bba15f167 100644 --- a/ext/opentelemetry-ext-opentracing-shim/README.rst +++ b/ext/opentelemetry-ext-opentracing-shim/README.rst @@ -1,5 +1,5 @@ OpenTracing Shim for OpenTelemetry -============================================================================ +================================== |pypi| @@ -16,4 +16,5 @@ Installation References ---------- +* `OpenTracing Shim for OpenTelemetry `_ * `OpenTelemetry Project `_ diff --git a/ext/opentelemetry-ext-otcollector/README.rst b/ext/opentelemetry-ext-otcollector/README.rst index 8c18b65223..1a0e3c330e 100644 --- a/ext/opentelemetry-ext-otcollector/README.rst +++ b/ext/opentelemetry-ext-otcollector/README.rst @@ -16,83 +16,9 @@ Installation pip install opentelemetry-ext-otcollector -Traces Usage ------------- - -The **OpenTelemetry Collector Exporter** allows to export `OpenTelemetry`_ traces to `OpenTelemetry Collector`_. - -.. code:: python - - from opentelemetry import trace - from opentelemetry.ext.otcollector.trace_exporter import CollectorSpanExporter - from opentelemetry.sdk.trace import TracerProvider - from opentelemetry.sdk.trace.export import BatchExportSpanProcessor - - - # create a CollectorSpanExporter - collector_exporter = CollectorSpanExporter( - # optional: - # endpoint="myCollectorUrl:55678", - # service_name="test_service", - # host_name="machine/container name", - ) - - # Create a BatchExportSpanProcessor and add the exporter to it - span_processor = BatchExportSpanProcessor(collector_exporter) - - # Configure the tracer to use the collector exporter - tracer_provider = TracerProvider() - tracer_provider.add_span_processor(span_processor) - tracer = TracerProvider().get_tracer(__name__) - - with tracer.start_as_current_span("foo"): - print("Hello world!") - -Metrics Usage -------------- - -The **OpenTelemetry Collector Exporter** allows to export `OpenTelemetry`_ metrics to `OpenTelemetry Collector`_. - -.. code:: python - - from opentelemetry import metrics - from opentelemetry.ext.otcollector.metrics_exporter import CollectorMetricsExporter - from opentelemetry.sdk.metrics import Counter, MeterProvider - from opentelemetry.sdk.metrics.export.controller import PushController - - - # create a CollectorMetricsExporter - collector_exporter = CollectorMetricsExporter( - # optional: - # endpoint="myCollectorUrl:55678", - # service_name="test_service", - # host_name="machine/container name", - ) - - # Meter is responsible for creating and recording metrics - metrics.set_meter_provider(MeterProvider()) - meter = metrics.get_meter(__name__) - # controller collects metrics created from meter and exports it via the - # exporter every interval - controller = PushController(meter, collector_exporter, 5) - counter = meter.create_metric( - "requests", - "number of requests", - "requests", - int, - Counter, - ("environment",), - ) - # Labelsets are used to identify key-values that are associated with a specific - # metric that you want to record. These are useful for pre-aggregation and can - # be used to store custom dimensions pertaining to a metric - label_set = meter.get_label_set({"environment": "staging"}) - - counter.add(25, label_set) - - References ---------- +* `OpenTelemetry Collector Exporter `_ * `OpenTelemetry Collector `_ * `OpenTelemetry `_ diff --git a/ext/opentelemetry-ext-otcollector/src/opentelemetry/ext/otcollector/__init__.py b/ext/opentelemetry-ext-otcollector/src/opentelemetry/ext/otcollector/__init__.py index 6ab2e961ec..0b2c26cb1d 100644 --- a/ext/opentelemetry-ext-otcollector/src/opentelemetry/ext/otcollector/__init__.py +++ b/ext/opentelemetry-ext-otcollector/src/opentelemetry/ext/otcollector/__init__.py @@ -11,3 +11,76 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. + +""" +The **OpenTelemetry Collector Exporter** allows to export OpenTelemetry traces to OpenTelemetry Collector. + +.. code:: python + + from opentelemetry import trace + from opentelemetry.ext.otcollector.trace_exporter import CollectorSpanExporter + from opentelemetry.sdk.trace import TracerProvider + from opentelemetry.sdk.trace.export import BatchExportSpanProcessor + + + # create a CollectorSpanExporter + collector_exporter = CollectorSpanExporter( + # optional: + # endpoint="myCollectorUrl:55678", + # service_name="test_service", + # host_name="machine/container name", + ) + + # Create a BatchExportSpanProcessor and add the exporter to it + span_processor = BatchExportSpanProcessor(collector_exporter) + + # Configure the tracer to use the collector exporter + tracer_provider = TracerProvider() + tracer_provider.add_span_processor(span_processor) + tracer = TracerProvider().get_tracer(__name__) + + with tracer.start_as_current_span("foo"): + print("Hello world!") + +Metrics Usage +------------- + +The **OpenTelemetry Collector Exporter** allows to export OpenTelemetry metrics to OpenTelemetry Collector. + +.. code:: python + + from opentelemetry import metrics + from opentelemetry.ext.otcollector.metrics_exporter import CollectorMetricsExporter + from opentelemetry.sdk.metrics import Counter, MeterProvider + from opentelemetry.sdk.metrics.export.controller import PushController + + + # create a CollectorMetricsExporter + collector_exporter = CollectorMetricsExporter( + # optional: + # endpoint="myCollectorUrl:55678", + # service_name="test_service", + # host_name="machine/container name", + ) + + # Meter is responsible for creating and recording metrics + metrics.set_meter_provider(MeterProvider()) + meter = metrics.get_meter(__name__) + # controller collects metrics created from meter and exports it via the + # exporter every interval + controller = PushController(meter, collector_exporter, 5) + counter = meter.create_metric( + "requests", + "number of requests", + "requests", + int, + Counter, + ("environment",), + ) + # Labelsets are used to identify key-values that are associated with a specific + # metric that you want to record. These are useful for pre-aggregation and can + # be used to store custom dimensions pertaining to a metric + label_set = meter.get_label_set({"environment": "staging"}) + + counter.add(25, label_set) +""" diff --git a/ext/opentelemetry-ext-prometheus/README.rst b/ext/opentelemetry-ext-prometheus/README.rst index f9e3d9416b..5a85f03582 100644 --- a/ext/opentelemetry-ext-prometheus/README.rst +++ b/ext/opentelemetry-ext-prometheus/README.rst @@ -15,58 +15,9 @@ Installation pip install opentelemetry-ext-prometheus - -Usage ------ - -The **OpenTelemetry Prometheus Exporter** allows to export `OpenTelemetry`_ metrics to `Prometheus`_. - - -.. _Prometheus: https://prometheus.io/ -.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/ - -.. code:: python - - from opentelemetry import metrics - from opentelemetry.ext.prometheus import PrometheusMetricsExporter - from opentelemetry.sdk.metrics import Counter, MeterProvider - from opentelemetry.sdk.metrics.export.controller import PushController - from prometheus_client import start_http_server - - # Start Prometheus client - start_http_server(port=8000, addr="localhost") - - # Meter is responsible for creating and recording metrics - metrics.set_meter_provider(MeterProvider()) - meter = metrics.meter() - # exporter to export metrics to Prometheus - prefix = "MyAppPrefix" - exporter = PrometheusMetricsExporter(prefix) - # controller collects metrics created from meter and exports it via the - # exporter every interval - controller = PushController(meter, exporter, 5) - - counter = meter.create_metric( - "requests", - "number of requests", - "requests", - int, - Counter, - ("environment",), - ) - - # Labelsets are used to identify key-values that are associated with a specific - # metric that you want to record. These are useful for pre-aggregation and can - # be used to store custom dimensions pertaining to a metric - label_set = meter.get_label_set({"environment": "staging"}) - - counter.add(25, label_set) - input("Press any key to exit...") - - - References ---------- +* `OpenTelemetry Prometheus Exporter `_ * `Prometheus `_ * `OpenTelemetry Project `_ diff --git a/ext/opentelemetry-ext-prometheus/src/opentelemetry/ext/prometheus/__init__.py b/ext/opentelemetry-ext-prometheus/src/opentelemetry/ext/prometheus/__init__.py index ebe68e3f4d..533355aaf8 100644 --- a/ext/opentelemetry-ext-prometheus/src/opentelemetry/ext/prometheus/__init__.py +++ b/ext/opentelemetry-ext-prometheus/src/opentelemetry/ext/prometheus/__init__.py @@ -12,7 +12,59 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Prometheus Metrics Exporter for OpenTelemetry.""" +""" +This library allows export of metrics data to `Prometheus `_. + +Usage +----- + +The **OpenTelemetry Prometheus Exporter** allows export of `OpenTelemetry`_ metrics to `Prometheus`_. + + +.. _Prometheus: https://prometheus.io/ +.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/ + +.. code:: python + + from opentelemetry import metrics + from opentelemetry.ext.prometheus import PrometheusMetricsExporter + from opentelemetry.sdk.metrics import Counter, Meter + from opentelemetry.sdk.metrics.export.controller import PushController + from prometheus_client import start_http_server + + # Start Prometheus client + start_http_server(port=8000, addr="localhost") + + # Meter is responsible for creating and recording metrics + metrics.set_meter_provider(MeterProvider()) + meter = metrics.meter() + # exporter to export metrics to Prometheus + prefix = "MyAppPrefix" + exporter = PrometheusMetricsExporter(prefix) + # controller collects metrics created from meter and exports it via the + # exporter every interval + controller = PushController(meter, exporter, 5) + + counter = meter.create_metric( + "requests", + "number of requests", + "requests", + int, + Counter, + ("environment",), + ) + + # Labelsets are used to identify key-values that are associated with a specific + # metric that you want to record. These are useful for pre-aggregation and can + # be used to store custom dimensions pertaining to a metric + label_set = meter.get_label_set({"environment": "staging"}) + + counter.add(25, label_set) + input("Press any key to exit...") + +API +--- +""" import collections import logging diff --git a/ext/opentelemetry-ext-psycopg2/README.rst b/ext/opentelemetry-ext-psycopg2/README.rst index 00222a4013..18cee0c2b2 100644 --- a/ext/opentelemetry-ext-psycopg2/README.rst +++ b/ext/opentelemetry-ext-psycopg2/README.rst @@ -1,30 +1,20 @@ -OpenTelemetry Psycopg integration +OpenTelemetry Psycopg Integration ================================= -The integration with PostgreSQL supports the `Psycopg`_ library and is specified -to ``trace_integration`` using ``'PostgreSQL'``. +|pypi| -.. _Psycopg: http://initd.org/psycopg/ +.. |pypi| image:: https://badge.fury.io/py/opentelemetry-ext-psycopg2.svg + :target: https://pypi.org/project/opentelemetry-ext-psycopg2/ -Usage ------ +Installation +------------ -.. code-block:: python +:: - import psycopg2 - from opentelemetry import trace - from opentelemetry.sdk.trace import TracerProvider - from opentelemetry.trace.ext.psycopg2 import trace_integration + pip install opentelemetry-ext-psycopg2 - trace.set_tracer_provider(TracerProvider()) - tracer = trace.get_tracer(__name__) - trace_integration(tracer) - cnx = psycopg2.connect(database='Database') - cursor = cnx.cursor() - cursor.execute("INSERT INTO test (testField) VALUES (123)") - cursor.close() - cnx.close() References ---------- +* `OpenTelemetry Psycopg Integration `_ * `OpenTelemetry Project `_ diff --git a/ext/opentelemetry-ext-psycopg2/src/opentelemetry/ext/psycopg2/__init__.py b/ext/opentelemetry-ext-psycopg2/src/opentelemetry/ext/psycopg2/__init__.py index 4181688489..f2fb4c4098 100644 --- a/ext/opentelemetry-ext-psycopg2/src/opentelemetry/ext/psycopg2/__init__.py +++ b/ext/opentelemetry-ext-psycopg2/src/opentelemetry/ext/psycopg2/__init__.py @@ -13,8 +13,32 @@ # limitations under the License. """ -The opentelemetry-ext-psycopg2 package allows tracing PostgreSQL queries made by the -Psycopg2 library. +The integration with PostgreSQL supports the `Psycopg`_ library and is specified +to ``trace_integration`` using ``'PostgreSQL'``. + +.. _Psycopg: http://initd.org/psycopg/ + +Usage +----- + +.. code-block:: python + + import psycopg2 + from opentelemetry import trace + from opentelemetry.sdk.trace import TracerProvider + from opentelemetry.trace.ext.psycopg2 import trace_integration + + trace.set_tracer_provider(TracerProvider()) + tracer = trace.get_tracer(__name__) + trace_integration(tracer) + cnx = psycopg2.connect(database='Database') + cursor = cnx.cursor() + cursor.execute("INSERT INTO test (testField) VALUES (123)") + cursor.close() + cnx.close() + +API +--- """ import logging diff --git a/ext/opentelemetry-ext-pymongo/README.rst b/ext/opentelemetry-ext-pymongo/README.rst index a4ecd9c904..ada56efed9 100644 --- a/ext/opentelemetry-ext-pymongo/README.rst +++ b/ext/opentelemetry-ext-pymongo/README.rst @@ -1,27 +1,21 @@ -OpenTelemetry pymongo integration +OpenTelemetry pymongo Integration ================================= -The integration with MongoDB supports the `pymongo`_ library and is specified -to ``trace_integration`` using ``'pymongo'``. +|pypi| -.. _pymongo: https://pypi.org/project/pymongo +.. |pypi| image:: https://badge.fury.io/py/opentelemetry-ext-pymongo.svg + :target: https://pypi.org/project/opentelemetry-ext-pymongo/ -Usage ------ +Installation +------------ -.. code:: python +:: - from pymongo import MongoClient - from opentelemetry.trace import tracer_provider - from opentelemetry.trace.ext.pymongo import trace_integration + pip install opentelemetry-ext-pymongo - trace_integration(tracer_provider()) - client = MongoClient() - db = client["MongoDB_Database"] - collection = db["MongoDB_Collection"] - collection.find_one() References ---------- - +* `OpenTelemetry pymongo Integration `_ * `OpenTelemetry Project `_ + diff --git a/ext/opentelemetry-ext-pymongo/src/opentelemetry/ext/pymongo/__init__.py b/ext/opentelemetry-ext-pymongo/src/opentelemetry/ext/pymongo/__init__.py index 3c95a30615..b27101e590 100644 --- a/ext/opentelemetry-ext-pymongo/src/opentelemetry/ext/pymongo/__init__.py +++ b/ext/opentelemetry-ext-pymongo/src/opentelemetry/ext/pymongo/__init__.py @@ -13,8 +13,28 @@ # limitations under the License. """ -The opentelemetry-ext-pymongo package allows tracing commands made by the -pymongo library. +The integration with MongoDB supports the `pymongo`_ library and is specified +to ``trace_integration`` using ``'pymongo'``. + +.. _pymongo: https://pypi.org/project/pymongo + +Usage +----- + +.. code:: python + + from pymongo import MongoClient + from opentelemetry.trace import tracer_provider + from opentelemetry.trace.ext.pymongo import trace_integration + + trace_integration(tracer_provider()) + client = MongoClient() + db = client["MongoDB_Database"] + collection = db["MongoDB_Collection"] + collection.find_one() + +API +--- """ from pymongo import monitoring diff --git a/ext/opentelemetry-ext-wsgi/README.rst b/ext/opentelemetry-ext-wsgi/README.rst index 82641bcaa4..12ee81cb09 100644 --- a/ext/opentelemetry-ext-wsgi/README.rst +++ b/ext/opentelemetry-ext-wsgi/README.rst @@ -18,43 +18,9 @@ Installation pip install opentelemetry-ext-wsgi -Usage (Flask) -------------- - -.. code-block:: python - - from flask import Flask - from opentelemetry.ext.wsgi import OpenTelemetryMiddleware - - app = Flask(__name__) - app.wsgi_app = OpenTelemetryMiddleware(app.wsgi_app) - - @app.route("/") - def hello(): - return "Hello!" - - if __name__ == "__main__": - app.run(debug=True) - - -Usage (Django) --------------- - -Modify the application's ``wsgi.py`` file as shown below. - -.. code-block:: python - - import os - from opentelemetry.ext.wsgi import OpenTelemetryMiddleware - from django.core.wsgi import get_wsgi_application - - os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'application.settings') - - application = get_wsgi_application() - application = OpenTelemetryMiddleware(application) - References ---------- +* `OpenTelemetry WSGI Middleware `_ * `OpenTelemetry Project `_ * `WSGI `_ diff --git a/ext/opentelemetry-ext-wsgi/src/opentelemetry/ext/wsgi/__init__.py b/ext/opentelemetry-ext-wsgi/src/opentelemetry/ext/wsgi/__init__.py index b96fc057d1..aa015fab2b 100644 --- a/ext/opentelemetry-ext-wsgi/src/opentelemetry/ext/wsgi/__init__.py +++ b/ext/opentelemetry-ext-wsgi/src/opentelemetry/ext/wsgi/__init__.py @@ -13,9 +13,43 @@ # limitations under the License. """ -The opentelemetry-ext-wsgi package provides a WSGI middleware that can be used -on any WSGI framework (such as Django / Flask) to track requests timing through -OpenTelemetry. +This library provides a WSGI middleware that can be used on any WSGI framework +(such as Django / Flask) to track requests timing through OpenTelemetry. + +Usage (Flask) +------------- + +.. code-block:: python + + from flask import Flask + from opentelemetry.ext.wsgi import OpenTelemetryMiddleware + + app = Flask(__name__) + app.wsgi_app = OpenTelemetryMiddleware(app.wsgi_app) + + @app.route("/") + def hello(): + return "Hello!" + + if __name__ == "__main__": + app.run(debug=True) + + +Usage (Django) +-------------- + +Modify the application's ``wsgi.py`` file as shown below. + +.. code-block:: python + + import os + from opentelemetry.ext.wsgi import OpenTelemetryMiddleware + from django.core.wsgi import get_wsgi_application + + os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'application.settings') + + application = get_wsgi_application() + application = OpenTelemetryMiddleware(application) """ import functools diff --git a/ext/opentelemetry-ext-zipkin/README.rst b/ext/opentelemetry-ext-zipkin/README.rst index af119fb410..c746051992 100644 --- a/ext/opentelemetry-ext-zipkin/README.rst +++ b/ext/opentelemetry-ext-zipkin/README.rst @@ -16,52 +16,9 @@ Installation pip install opentelemetry-ext-zipkin -Usage ------ - -The **OpenTelemetry Zipkin Exporter** allows to export `OpenTelemetry`_ traces to `Zipkin`_. -This exporter always send traces to the configured Zipkin collector using HTTP. - - -.. _Zipkin: https://zipkin.io/ -.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/ - -.. code:: python - - from opentelemetry import trace - from opentelemetry.ext import zipkin - from opentelemetry.sdk.trace import TracerProvider - from opentelemetry.sdk.trace.export import BatchExportSpanProcessor - - trace.set_tracer_provider(TracerProvider()) - tracer = trace.get_tracer(__name__) - - # create a ZipkinSpanExporter - zipkin_exporter = zipkin.ZipkinSpanExporter( - service_name="my-helloworld-service", - # optional: - # host_name="localhost", - # port=9411, - # endpoint="/api/v2/spans", - # protocol="http", - # ipv4="", - # ipv6="", - # retry=False, - ) - - # Create a BatchExportSpanProcessor and add the exporter to it - span_processor = BatchExportSpanProcessor(zipkin_exporter) - - # add to the tracer - trace.tracer_provider().add_span_processor(span_processor) - - with tracer.start_as_current_span("foo"): - print("Hello world!") - -The `examples <./examples>`_ folder contains more elaborated examples. - References ---------- +* `OpenTelemetry Zipkin Exporter `_ * `Zipkin `_ * `OpenTelemetry Project `_ diff --git a/ext/opentelemetry-ext-zipkin/src/opentelemetry/ext/zipkin/__init__.py b/ext/opentelemetry-ext-zipkin/src/opentelemetry/ext/zipkin/__init__.py index 077fa9a6b4..01e455a831 100644 --- a/ext/opentelemetry-ext-zipkin/src/opentelemetry/ext/zipkin/__init__.py +++ b/ext/opentelemetry-ext-zipkin/src/opentelemetry/ext/zipkin/__init__.py @@ -12,7 +12,62 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""Zipkin Span Exporter for OpenTelemetry.""" +""" +This library allows to export tracing data to `Zipkin `_. + +Installation +------------ + +:: + + pip install opentelemetry-ext-zipkin + + +Usage +----- + +The **OpenTelemetry Zipkin Exporter** allows to export `OpenTelemetry`_ traces to `Zipkin`_. +This exporter always send traces to the configured Zipkin collector using HTTP. + + +.. _Zipkin: https://zipkin.io/ +.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/ + +.. code:: python + + from opentelemetry import trace + from opentelemetry.ext import zipkin + from opentelemetry.sdk.trace import TracerProvider + from opentelemetry.sdk.trace.export import BatchExportSpanProcessor + + trace.set_tracer_provider(TracerProvider()) + tracer = trace.get_tracer(__name__) + + # create a ZipkinSpanExporter + zipkin_exporter = zipkin.ZipkinSpanExporter( + service_name="my-helloworld-service", + # optional: + # host_name="localhost", + # port=9411, + # endpoint="/api/v2/spans", + # protocol="http", + # ipv4="", + # ipv6="", + # retry=False, + ) + + # Create a BatchExportSpanProcessor and add the exporter to it + span_processor = BatchExportSpanProcessor(zipkin_exporter) + + # add to the tracer + trace.tracer_provider().add_span_processor(span_processor) + + with tracer.start_as_current_span("foo"): + print("Hello world!") + +API +--- +""" import json import logging diff --git a/tox.ini b/tox.ini index 52c82eba07..2eb35491da 100644 --- a/tox.ini +++ b/tox.ini @@ -211,6 +211,7 @@ deps = mysql-connector-python wrapt psycopg2-binary + prometheus_client changedir = docs