diff --git a/docs/api/api.rst b/docs/api/index.rst similarity index 100% rename from docs/api/api.rst rename to docs/api/index.rst diff --git a/docs/examples/index.rst b/docs/examples/index.rst new file mode 100644 index 00000000000..92fc679b701 --- /dev/null +++ b/docs/examples/index.rst @@ -0,0 +1,10 @@ +:orphan: + +Examples +======== + +.. toctree:: + :maxdepth: 1 + :glob: + + ** diff --git a/docs/exporter/index.rst b/docs/exporter/index.rst new file mode 100644 index 00000000000..df1d06294d3 --- /dev/null +++ b/docs/exporter/index.rst @@ -0,0 +1,11 @@ +:orphan: +:hidden: + +Exporters +========= + +.. toctree:: + :maxdepth: 1 + :glob: + + ** diff --git a/docs/faq-and-cookbook.rst b/docs/faq-and-cookbook.rst deleted file mode 100644 index 2aacb3eeb4f..00000000000 --- a/docs/faq-and-cookbook.rst +++ /dev/null @@ -1,136 +0,0 @@ -Frequently Asked Questions and Cookbook -======================================= - -This page answers frequently asked questions, and serves as a cookbook -for common scenarios. - -Create a new span ------------------ - -.. code-block:: python - - from opentelemetry import trace - - tracer = trace.get_tracer(__name__) - with tracer.start_as_current_span("print") as span: - print("foo") - span.set_attribute("printed_string", "foo") - -Getting and modifying a span ----------------------------- - -.. code-block:: python - - from opentelemetry import trace - - current_span = trace.get_current_span() - current_span.set_attribute("hometown", "seattle") - -Create a nested span --------------------- - -.. code-block:: python - - from opentelemetry import trace - import time - - tracer = trace.get_tracer(__name__) - - # Create a new span to track some work - with tracer.start_as_current_span("parent"): - time.sleep(1) - - # Create a nested span to track nested work - with tracer.start_as_current_span("child"): - time.sleep(2) - # the nested span is closed when it's out of scope - - # Now the parent span is the current span again - time.sleep(1) - - # This span is also closed when it goes out of scope - - -Capturing baggage at different contexts ---------------------------------------- - -.. code-block:: python - - from opentelemetry import trace - - tracer = trace.get_tracer(__name__) - with tracer.start_as_current_span(name="root span") as root_span: - parent_ctx = baggage.set_baggage("context", "parent") - with tracer.start_as_current_span( - name="child span", context=parent_ctx - ) as child_span: - child_ctx = baggage.set_baggage("context", "child") - - print(baggage.get_baggage("context", parent_ctx)) - print(baggage.get_baggage("context", child_ctx)) - -Manually setting span context ------------------------------ - -.. code-block:: python - - from opentelemetry import trace - from opentelemetry.trace import NonRecordingSpan, SpanContext, TraceFlags - from opentelemetry.sdk.trace import TracerProvider - from opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor - from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator - - trace.set_tracer_provider(TracerProvider()) - trace.get_tracer_provider().add_span_processor(BatchSpanProcessor(ConsoleSpanExporter())) - - tracer = trace.get_tracer(__name__) - - # Extracting from carrier header - carrier = {'traceparent': '00-a9c3b99a95cc045e573e163c3ac80a77-d99d251a8caecd06-01'} - ctx = TraceContextTextMapPropagator().extract(carrier=carrier) - - with tracer.start_as_current_span('child', context=ctx) as span: - span.set_attribute('primes', [2, 3, 5, 7]) - - # Or if you have a SpanContext object already. - span_context = SpanContext( - trace_id=2604504634922341076776623263868986797, - span_id=5213367945872657620, - is_remote=True, - trace_flags=TraceFlags(0x01) - ) - ctx = trace.set_span_in_context(NonRecordingSpan(span_context)) - - with tracer.start_as_current_span("child", context=ctx) as span: - span.set_attribute('evens', [2, 4, 6, 8]) - -Using multiple tracer providers with different Resource -------------------------------------------------------- - -.. code-block:: python - - from opentelemetry import trace - from opentelemetry.sdk.trace import TracerProvider - from opentelemetry.sdk.resources import Resource - from opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor - - # Global tracer provider which can be set only once - trace.set_tracer_provider( - TracerProvider(resource=Resource.create({"service.name": "service1"})) - ) - trace.get_tracer_provider().add_span_processor(BatchSpanProcessor(ConsoleSpanExporter())) - - tracer = trace.get_tracer(__name__) - with tracer.start_as_current_span("some-name") as span: - span.set_attribute("key", "value") - - - - another_tracer_provider = TracerProvider( - resource=Resource.create({"service.name": "service2"}) - ) - another_tracer_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter())) - - another_tracer = trace.get_tracer(__name__, tracer_provider=another_tracer_provider) - with another_tracer.start_as_current_span("name-here") as span: - span.set_attribute("another-key", "another-value") diff --git a/docs/getting-started.rst b/docs/getting-started.rst deleted file mode 100644 index c4db11c24a2..00000000000 --- a/docs/getting-started.rst +++ /dev/null @@ -1,253 +0,0 @@ -Getting Started -=============== - -This guide walks you through instrumenting a Python application with ``opentelemetry-python``. - -For more elaborate examples, see `examples `_. - -Hello world: emit a trace to your console ---------------------------------------------- - -To get started, install both the opentelemetry API and SDK: - -.. code-block:: sh - - pip install opentelemetry-api - pip install opentelemetry-sdk - -The API package provides the interfaces required by the application owner, as well -as some helper logic to load implementations. - -The SDK provides an implementation of those interfaces. The implementation is designed to be generic and extensible enough -that in many situations, the SDK is sufficient. - -Once installed, you can use the packages to emit spans from your application. A span -represents an action within your application that you want to instrument, such as an HTTP request -or a database call. Once instrumented, you can extract helpful information such as -how long the action took. You can also add arbitrary attributes to the span that provide more insight for debugging. - -The following example script emits a trace containing three named spans: "foo", "bar", and "baz": - -.. literalinclude:: getting_started/tracing_example.py - :language: python - :lines: 15- - -When you run the script you can see the traces printed to your console: - -.. code-block:: sh - - $ python tracing_example.py - { - "name": "baz", - "context": { - "trace_id": "0xb51058883c02f880111c959f3aa786a2", - "span_id": "0xb2fa4c39f5f35e13", - "trace_state": "{}" - }, - "kind": "SpanKind.INTERNAL", - "parent_id": "0x77e577e6a8813bf4", - "start_time": "2020-05-07T14:39:52.906272Z", - "end_time": "2020-05-07T14:39:52.906343Z", - "status": { - "status_code": "OK" - }, - "attributes": {}, - "events": [], - "links": [] - } - { - "name": "bar", - "context": { - "trace_id": "0xb51058883c02f880111c959f3aa786a2", - "span_id": "0x77e577e6a8813bf4", - "trace_state": "{}" - }, - "kind": "SpanKind.INTERNAL", - "parent_id": "0x3791d950cc5140c5", - "start_time": "2020-05-07T14:39:52.906230Z", - "end_time": "2020-05-07T14:39:52.906601Z", - "status": { - "status_code": "OK" - }, - "attributes": {}, - "events": [], - "links": [] - } - { - "name": "foo", - "context": { - "trace_id": "0xb51058883c02f880111c959f3aa786a2", - "span_id": "0x3791d950cc5140c5", - "trace_state": "{}" - }, - "kind": "SpanKind.INTERNAL", - "parent_id": null, - "start_time": "2020-05-07T14:39:52.906157Z", - "end_time": "2020-05-07T14:39:52.906743Z", - "status": { - "status_code": "OK" - }, - "attributes": {}, - "events": [], - "links": [] - } - -Each span typically represents a single operation or unit of work. -Spans can be nested, and have a parent-child relationship with other spans. -While a given span is active, newly-created spans inherit the active span's trace ID, options, and other attributes of its context. -A span without a parent is called the root span, and a trace is comprised of one root span and its descendants. - -In this example, the OpenTelemetry Python library creates one trace containing three spans and prints it to STDOUT. - -Configure exporters to emit spans elsewhere -------------------------------------------- - -The previous example does emit information about all spans, but the output is a bit hard to read. -In most cases, you can instead *export* this data to an application performance monitoring backend to be visualized and queried. -It's also common to aggregate span and trace information from multiple services into a single database, so that actions requiring multiple services can still all be visualized together. - -This concept of aggregating span and trace information is known as distributed tracing. One such distributed tracing backend is known as Jaeger. The Jaeger project provides an all-in-one Docker container with a UI, database, and consumer. - -Run the following command to start Jaeger: - -.. code-block:: sh - - docker run -p 16686:16686 -p 6831:6831/udp jaegertracing/all-in-one - -This command starts Jaeger locally on port 16686 and exposes the Jaeger thrift agent on port 6831. You can visit Jaeger at http://localhost:16686. - -After you spin up the backend, your application needs to export traces to this system. Although ``opentelemetry-sdk`` doesn't provide an exporter -for Jaeger, you can install it as a separate package with the following command: - -.. code-block:: sh - - pip install opentelemetry-exporter-jaeger - -After you install the exporter, update your code to import the Jaeger exporter and use that instead: - -.. literalinclude:: getting_started/jaeger_example.py - :language: python - :lines: 15- - -Finally, run the Python script: - -.. code-block:: python - - python jaeger_example.py - -You can then visit the Jaeger UI, see your service under "services", and find your traces! - -Instrumentation example with Flask ------------------------------------- - -While the example in the previous section is great, it's very manual. The following are common actions you might want to track and include as part of your distributed tracing. - -* HTTP responses from web services -* HTTP requests from clients -* Database calls - -To track these common actions, OpenTelemetry has the concept of instrumentations. Instrumentations are packages designed to interface -with a specific framework or library, such as Flask and psycopg2. You can find a list of the currently curated extension packages in the `Contrib repository `_. - -Instrument a basic Flask application that uses the requests library to send HTTP requests. First, install the instrumentation packages themselves: - -.. code-block:: sh - - pip install opentelemetry-instrumentation-flask - pip install opentelemetry-instrumentation-requests - - -The following small Flask application sends an HTTP request and also activates each instrumentation during its initialization: - -.. literalinclude:: getting_started/flask_example.py - :language: python - :lines: 15- - - -Now run the script, hit the root URL (http://localhost:5000/) a few times, and watch your spans be emitted! - -.. code-block:: sh - - python flask_example.py - - -Configure Your HTTP propagator (b3, Baggage) -------------------------------------------------------- - -A major feature of distributed tracing is the ability to correlate a trace across -multiple services. However, those services need to propagate information about a -trace from one service to the other. - -To enable this propagation, OpenTelemetry has the concept of `propagators `_, -which provide a common method to encode and decode span information from a request and response, respectively. - -By default, ``opentelemetry-python`` is configured to use the `W3C Trace Context `_ -and `W3C Baggage `_ HTTP headers for HTTP requests, but you can configure it to leverage different propagators. Here's -an example using Zipkin's `b3 propagation `_: - -.. code-block:: sh - - pip install opentelemetry-propagator-b3 - -Following the installation of the package containing the b3 propagator, configure the propagator as follows: - -.. code-block:: python - - from opentelemetry.propagate import set_global_textmap - from opentelemetry.propagators.b3 import B3Format - - set_global_textmap(B3Format()) - -Use the OpenTelemetry Collector for traces ------------------------------------------- - -Although it's possible to directly export your telemetry data to specific backends, you might have more complex use cases such as the following: - -* A single telemetry sink shared by multiple services, to reduce overhead of switching exporters. -* Aggregating traces across multiple services, running on multiple hosts. - -To enable a broad range of aggregation strategies, OpenTelemetry provides the `opentelemetry-collector `_. -The Collector is a flexible application that can consume trace data and export to multiple other backends, including to another instance of the Collector. - -Start the Collector locally to see how the Collector works in practice. Write the following file: - -.. code-block:: yaml - - # /tmp/otel-collector-config.yaml - receivers: - otlp: - protocols: - grpc: - http: - exporters: - logging: - loglevel: debug - processors: - batch: - service: - pipelines: - traces: - receivers: [otlp] - exporters: [logging] - processors: [batch] - -Then start the Docker container: - -.. code-block:: sh - - docker run -p 4317:4317 \ - -v /tmp/otel-collector-config.yaml:/etc/otel-collector-config.yaml \ - otel/opentelemetry-collector:latest \ - --config=/etc/otel-collector-config.yaml - -Install the OpenTelemetry Collector exporter: - -.. code-block:: sh - - pip install opentelemetry-exporter-otlp - -Finally, execute the following script: - -.. literalinclude:: getting_started/otlpcollector_example.py - :language: python - :lines: 15- diff --git a/docs/index.rst b/docs/index.rst index 4344bab2ba0..c01557463ff 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,117 +1,44 @@ -OpenTelemetry-Python -==================== - -The Python `OpenTelemetry `_ client. +OpenTelemetry Python API Reference +================================== .. image:: https://img.shields.io/badge/slack-chat-green.svg :target: https://cloud-native.slack.com/archives/C01PD4HUVBL :alt: Slack Chat +Welcome to the **API docs** for the `Python OpenTelemetry client +`_. -This documentation describes the :doc:`opentelemetry-api `, -:doc:`opentelemetry-sdk `, and several `integration packages <#integrations>`_. - -The library is currently stable for tracing. Support for :doc:`metrics ` and -:doc:`logging ` are currently under development and are considered experimental. - -Requirement ------------ -OpenTelemetry-Python supports Python 3.6 and higher. - -Installation ------------- - -The API and SDK packages are available on PyPI, and can installed via pip: - -.. code-block:: sh - - pip install opentelemetry-api - pip install opentelemetry-sdk - -In addition, there are several extension packages which can be installed separately as:: - - pip install opentelemetry-exporter-{exporter} - pip install opentelemetry-instrumentation-{instrumentation} +For an introduction to OpenTelemetry, see the `OpenTelemetry website docs +`_. -These are for exporter and instrumentation packages respectively. -The Jaeger, Zipkin, OTLP and OpenCensus Exporters can be found in the :scm_web:`exporter ` -directory of the repository. Instrumentations and additional exporters can be found in the -`Contrib repo instrumentation `_ -and `Contrib repo exporter `_ directories. +To learn how to instrument your Python code, see `Getting Started +`_. For +project status, information about releases, installation instructions and more, +see `Python `_. -Extensions ----------- - -Visit `OpenTelemetry Registry `_ to find -related projects like exporters, instrumentation libraries, tracer implementations, etc. - -Installing Cutting Edge Packages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -While the project is pre-1.0, there may be significant functionality that -has not yet been released to PyPI. In that situation, you may want to -install the packages directly from the repo. This can be done by cloning the -repository and doing an `editable -install `_: - -.. code-block:: sh - - git clone https://github.com/open-telemetry/opentelemetry-python.git - cd opentelemetry-python - pip install -e ./opentelemetry-api - pip install -e ./opentelemetry-sdk +Getting Started +--------------- - -.. toctree:: - :maxdepth: 1 - :caption: Getting Started - :name: getting-started - - getting-started - faq-and-cookbook +* `Getting Started `_ +* `Frequently Asked Questions and Cookbook `_ .. toctree:: :maxdepth: 1 :caption: Core Packages :name: packages - api/api - sdk/sdk - -.. toctree:: - :maxdepth: 2 - :caption: Exporters - :name: exporters - :glob: - - exporter/** + api/index + sdk/index .. toctree:: :maxdepth: 2 - :caption: Shims - :name: Shims - :glob: - - shim/** - -.. toctree:: - :maxdepth: 1 - :caption: Performance - :name: performance-tests - :glob: - - performance/** - -.. toctree:: - :maxdepth: 1 - :caption: Examples - :name: examples + :caption: More :glob: - examples/** + exporter/index + shim/index + examples/index -Indices and tables ------------------- * :ref:`genindex` * :ref:`modindex` diff --git a/docs/performance/benchmarks.rst b/docs/performance/benchmarks.rst deleted file mode 100644 index 9c406c0323f..00000000000 --- a/docs/performance/benchmarks.rst +++ /dev/null @@ -1,4 +0,0 @@ -Performance Tests - Benchmarks -============================== - -Click `here `_ to view the latest performance benchmarks for packages in this repo. diff --git a/docs/sdk/sdk.rst b/docs/sdk/index.rst similarity index 100% rename from docs/sdk/sdk.rst rename to docs/sdk/index.rst diff --git a/docs/shim/index.rst b/docs/shim/index.rst new file mode 100644 index 00000000000..5fad3b36639 --- /dev/null +++ b/docs/shim/index.rst @@ -0,0 +1,10 @@ +:orphan: + +Shims +===== + +.. toctree:: + :maxdepth: 1 + :glob: + + **