.. role:: raw-html-m2r(raw)
   :format: html


Microsoft Opentelemetry exporter for Azure Monitor
==================================================


.. image:: https://img.shields.io/gitter/room/Microsoft/azure-monitor-python
   :target: https://gitter.im/Azure/azure-sdk-for-python
   :alt: Gitter chat


The exporter for Azure Monitor allows you to export tracing data utilizing the OpenTelemetry SDK and send telemetry data to Azure Monitor for applications written in Python.

`Source code <https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/monitor/azure-monitor-opentelemetry-exporter>`_ | `Package (PyPi) <https://pypi.org/project/azure-opentelemetry-exporter-azuremonitor>`_ | `API reference documentation <https://azuresdkdocs.blob.core.windows.net/$web/python/azure-opentelemetry-exporter-azuremonitor/1.0.0b2/index.html>`_ | `Product documentation <https://docs.microsoft.com/azure/azure-monitor/overview>`_ || `Samples <https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/monitor/azure-monitor-opentelemetry-exporter/samples>`_ | `Changelog <https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/azure-monitor-opentelemetry-exporter/CHANGELOG.md>`_

Getting started
---------------

Install the package
^^^^^^^^^^^^^^^^^^^

Install the Microsoft Opentelemetry exporter for Azure Monitor with `pip <https://pypi.org/project/pip/>`_\ :

.. code-block:: Bash

   pip install azure-monitor-opentelemetry-exporter --pre

Prerequisites:
^^^^^^^^^^^^^^

To use this package, you must have:


* Azure subscription - `Create a free account <https://azure.microsoft.com/free/>`_
* Azure Monitor - `How to use application insights <https://docs.microsoft.com/azure/azure-monitor/app/app-insights-overview#how-do-i-use-application-insights>`_
* Opentelemetry SDK - `Opentelemtry SDK for Python <https://github.com/open-telemetry/opentelemetry-python>`_
* Python 3.5 or later - `Install Python <https://www.python.org/downloads/>`_

Authenticate the client
^^^^^^^^^^^^^^^^^^^^^^^

Interaction with Azure monitor exporter starts with an instance of the ``AzureMonitorTraceExporter`` class. You will need a **connection_string** to instantiate the object.
Please find the samples linked below for demonstration as to how to authenticate using a connection string.

`Create Exporter from connection string <https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/azure-monitor-opentelemetry-exporter/samples/traces/sample_trace.py>`_
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: Python

   from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
   exporter = AzureMonitorTraceExporter.from_connection_string(
       connection_string = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
   )

You can also instantiate the exporter directly via the constructor. In this case, the connection string will be automatically populated from the ``APPLICATIONINSIGHTS_CONNECTION_STRING`` environment variable.

.. code-block:: python

   from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
   exporter = AzureMonitorTraceExporter()

Key concepts
------------

Some of the key concepts for the Azure monitor exporter include:


* 
  `Opentelemetry <https://opentelemetry.io/>`_\ : Opentelemetry is a set of libraries used to collect and export telemetry data (metrics, logs, and traces) for analysis in order to understand your software's performance and behavior.

* 
  `Instrumentation <https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#instrumentation-libraries>`_\ : The ability to call the opentelemetry API directly by any application is facilitated by instrumentaton. A library that enables OpenTelemetry observability for another library is called an Instrumentation Library.

* 
  `Trace <https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md#trace>`_\ : Trace refers to distributed tracing. It can be thought of as a directed acyclic graph (DAG) of Spans, where the edges between Spans are defined as parent/child relationship.

* 
  `Tracer Provider <https://opentelemetry-python.readthedocs.io/en/stable/api/trace.html?highlight=TracerProvider#opentelemetry.trace.TracerProvider>`_\ : Provides a ``Tracer`` for use by the given instrumentation library.

* 
  `Span Processor <https://opentelemetry-python.readthedocs.io/en/stable/_modules/opentelemetry/sdk/trace.html?highlight=SpanProcessor#>`_\ : A span processor allows hooks for SDK's ``Span`` start and end method invocations. Follow the link for more information.

* 
  `Sampling <https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#sampling>`_\ : Sampling is a mechanism to control the noise and overhead introduced by OpenTelemetry by reducing the number of samples of traces collected and sent to the backend.

* 
  `AzureMonitorTraceExporter <https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/monitor/azure-monitor-opentelemetry-exporter/azure/monitor/opentelemetry/exporter/export/trace/_exporter.py#L30>`_\ : This is the class that is initialized to send tracing related telemetry to Azure Monitor.

For more information about these resources, see `What is Azure Monitor? <https://docs.microsoft.com/azure/azure-monitor/overview>`_.

Examples
--------

The following sections provide several code snippets covering some of the most common tasks, including:


* `Exporting a custom span <#export-hello-world-trace>`_
* `Using an instrumentation to track a library <#instrumentation-with-requests-library>`_

Export Hello World Trace
^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: Python

   import os
   from opentelemetry import trace
   from opentelemetry.sdk.trace import TracerProvider
   from opentelemetry.sdk.trace.export import BatchSpanProcessor
   from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

   exporter = AzureMonitorTraceExporter.from_connection_string(
       connection_string = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING "]
   )

   trace.set_tracer_provider(TracerProvider())
   tracer = trace.get_tracer(__name__)
   span_processor = BatchSpanProcessor(exporter)
   trace.get_tracer_provider().add_span_processor(span_processor)

   with tracer.start_as_current_span("hello"):
       print("Hello, World!")

Instrumentation with requests library
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

OpenTelemetry also supports several instrumentations which allows to instrument with third party libraries.

This example shows how to instrument with the `requests <https://pypi.org/project/requests/>`_ library.


* Install the requests integration package using pip install opentelemetry-instrumentation-requests.

.. code-block:: Python

   import os
   import requests
   from opentelemetry import trace
   from opentelemetry.instrumentation.requests import RequestsInstrumentor
   from opentelemetry.sdk.trace import TracerProvider
   from opentelemetry.sdk.trace.export import BatchSpanProcessor

   from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

   trace.set_tracer_provider(TracerProvider())
   tracer = trace.get_tracer(__name__)

   # This line causes your calls made with the requests library to be tracked.
   RequestsInstrumentor().instrument()
   span_processor = BatchSpanProcessor(
       AzureMonitorTraceExporter.from_connection_string(
           os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING "]
       )
   )
   trace.get_tracer_provider().add_span_processor(span_processor)

   RequestsInstrumentor().instrument()

   # This request will be traced
   response = requests.get(url="https://azure.microsoft.com/")

Troubleshooting
---------------

The exporter raises exceptions defined in `Azure Core <https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/README.md#azure-core-library-exceptions>`_.

Next steps
----------

More sample code
^^^^^^^^^^^^^^^^

Please find further examples in the `samples <https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/monitor/azure-monitor-opentelemetry-exporter/samples>`_ directory demonstrating common scenarios.

Additional documentation
^^^^^^^^^^^^^^^^^^^^^^^^

For more extensive documentation on the Azure Monitor service, see the `Azure Monitor documentation <https://docs.microsoft.com/azure/azure-monitor/overview>`_ on docs.microsoft.com.

For detailed overview of Opentelemetry, visit their `overview <https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/overview.md>`_ page.

Contributing
------------

This project welcomes contributions and suggestions.  Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the `Microsoft Open Source Code of Conduct <https://opensource.microsoft.com/codeofconduct/>`_.
For more information see the `Code of Conduct FAQ <https://opensource.microsoft.com/codeofconduct/faq/>`_ or
contact `opencode@microsoft.com <mailto:opencode@microsoft.com>`_ with any additional questions or comments.

:raw-html-m2r:`<!-- LINKS -->`


Indices and tables
------------------

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

.. toctree::
  :maxdepth: 5
  :glob:
  :caption: Developer Documentation

  azure.monitor.opentelemetry.exporter.rst