.. OpenTelemetry documentation master file, created by
   sphinx-quickstart on Mon Jun  3 22:48:38 2019.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

OpenTelemetry-Python
====================

The Python `OpenTelemetry <https://opentelemetry.io/>`_ client.

.. image:: https://img.shields.io/gitter/room/opentelemetry/opentelemetry-python
   :target: https://gitter.im/open-telemetry/opentelemetry-python
   :alt: Gitter Chat


This documentation describes the opentelemetry-api, opentelemetry-sdk,
and several integration packages.

**Please note** that this library is currently in alpha, and shouldn't be
used in production environments.

Installation
------------

The API and SDK packages are available on PyPI, and can installed via pip:

.. code-block:: bash

    pip install opentelemetry-api
    pip install opentelemetry-sdk

In addition, there are several extension packages which can be installed separately as::

    pip install opentelemetry-ext-{integration}

The extension packages can be found in
`ext/ directory of the repository <https://github.com/open-telemetry/opentelemetry-python/tree/master/ext>`_.

In addition, third party exporters are available:

* `Azure Monitor <https://github.com/microsoft/opentelemetry-exporters-python/tree/master/azure_monitor>`_

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
repositry and doing an `editable
install <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_:

.. code-block:: bash
    git clone https://github.com/open-telemetry/opentelemetry-python.git
    cd opentelemetry-python
    pip install -e ./opentelemetry-api
    pip install -e ./opentelemetry-sdk
    pip install -e ./ext/opentelemetry-ext-{integration}


Quick Start
-----------

opentelemetry can be used to emit distributed traces and metrics from your application. 
The following are examples using the API and SDK:

Tracing
~~~~~~~

.. code-block:: python

    from opentelemetry import trace
    from opentelemetry.sdk.trace import TracerProvider
    from opentelemetry.sdk.trace.export import ConsoleSpanExporter
    from opentelemetry.sdk.trace.export import SimpleExportSpanProcessor

    trace.set_preferred_tracer_provider_implementation(lambda T: TracerProvider())
    trace.tracer_provider().add_span_processor(
        SimpleExportSpanProcessor(ConsoleSpanExporter())
    )
    tracer = trace.get_tracer(__name__)
    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!")

Metrics
~~~~~~~

.. code-block:: python

    from opentelemetry import metrics
    from opentelemetry.sdk.metrics import Counter, MeterProvider
    from opentelemetry.sdk.metrics.export import ConsoleMetricsExporter
    from opentelemetry.sdk.metrics.export.controller import PushController

    metrics.set_preferred_meter_provider_implementation(lambda _: MeterProvider())
    meter = metrics.get_meter(__name__)
    exporter = ConsoleMetricsExporter()
    controller = PushController(meter, exporter, 5)

    counter = meter.create_metric(
        "available memory",
        "available memory",
        "bytes",
        int,
        Counter,
        ("environment",),
    )

    label_values = ("staging",)
    counter_handle = counter.get_handle(label_values)
    counter_handle.add(100)

More examples are available in the `examples folder <https://github.com/open-telemetry/opentelemetry-python/tree/master/examples>`_.


.. toctree::
   :maxdepth: 1
   :caption: OpenTelemetry API:

   opentelemetry.context
   opentelemetry.metrics
   opentelemetry.trace
   opentelemetry.util.loader

.. toctree::
    :maxdepth: 1
    :caption: OpenTelemetry SDK:

    opentelemetry.sdk.context
    opentelemetry.sdk.metrics
    opentelemetry.sdk.trace


.. toctree::
    :maxdepth: 1
    :caption: OpenTelemetry Integrations:

    opentelemetry.ext.flask
    opentelemetry.ext.http_requests
    opentelemetry.ext.jaeger
    opentelemetry.ext.opentracing_shim
    opentelemetry.ext.pymongo
    opentelemetry.ext.wsgi

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`