Azure Monitor Opentelemetry Distro client library for Python - version 1.6.2

The Azure Monitor Distro of Opentelemetry Python is a "one-stop-shop" telemetry solution, requiring only one line of code to instrument your application. The distro captures telemetry via OpenTelemetry instrumentations and reports telemetry to Azure Monitor via the Azure Monitor exporters.

Prior to using this SDK, please read and understand Data Collection Basics, especially the section on telemetry types. OpenTelemetry terminology differs from Application Insights terminology so it is important to understand the way the telemetry types map to each other.

This distro automatically installs the following libraries:

• Azure Monitor OpenTelemetry exporters
• A subset of OpenTelemetry instrumentations that are officially supported as listed below.

Officially supported instrumentations

OpenTelemetry instrumentations allow automatic collection of requests sent from underlying instrumented libraries. The following is a list of OpenTelemetry instrumentations that come bundled in with the Azure monitor distro. These instrumentations are enabled by default. See the Usage section below for how to opt-out of these instrumentations.

If you would like to add support for another OpenTelemetry instrumentation, please submit a feature request. In the meantime, you can use the OpenTelemetry instrumentation manually via it's own APIs (i.e. instrument()) in your code. See this for an example.

Key concepts

This package bundles a series of OpenTelemetry and Azure Monitor components to enable the collection and sending of telemetry to Azure Monitor. For MANUAL instrumentation, use the configure_azure_monitor function. AUTOMATIC instrumentation is not yet supported.

The Azure Monitor OpenTelemetry exporters are the main components in accomplishing this. You will be able to use the exporters and their APIs directly through this package. Please go the exporter documentation to understand how OpenTelemetry and Azure Monitor components work in enabling telemetry collection and exporting.

Currently, all instrumentations available in OpenTelemetry are in a beta state, meaning they are not stable and may have breaking changes in the future. Efforts are being made in pushing these to a more stable state.

Getting started

Prerequisites

To use this package, you must have:

• Azure subscription - Create a free account
• Azure Monitor - How to use application insights
• Opentelemetry SDK - Opentelemetry SDK for Python
• Python 3.8 or later - Install Python

Install the package

Install the Azure Monitor Opentelemetry Distro with pip:

pip install azure-monitor-opentelemetry

Usage

You can use configure_azure_monitor to set up instrumentation for your app to Azure Monitor. configure_azure_monitor supports the following optional arguments. All pass-in parameters take priority over any related environment variables.

You can configure further with OpenTelemetry environment variables.

Azure monitor OpenTelemetry Exporter configurations

You can pass Azure monitor OpenTelemetry exporter configuration parameters directly into configure_azure_monitor. See additional configuration related to exporting here.

...
configure_azure_monitor(
   connection_string="<your-connection-string>",
   disable_offline_storage=True,
)
...

Examples

Samples are available here to demonstrate how to utilize the above configuration options.

Monitoring in Azure Functions

Trace correlation

Tracked incoming requests coming into your Python application hosted in Azure Functions will not be automatically correlated with telemetry being tracked within it. You can manually achieve trace correlation by extract the TraceContext directly as shown below:

import azure.functions as func

from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace
from opentelemetry.propagate import extract

# Configure Azure monitor collection telemetry pipeline
configure_azure_monitor()

def main(req: func.HttpRequest, context) -> func.HttpResponse:
   ...
   # Store current TraceContext in dictionary format
   carrier = {
      "traceparent": context.trace_context.Traceparent,
      "tracestate": context.trace_context.Tracestate,
   }
   tracer = trace.get_tracer(__name__)
   # Start a span using the current context
   with tracer.start_as_current_span(
      "http_trigger_span",
      context=extract(carrier),
   ):
      ...

Logging issues

The Azure Functions worker itself sends logging telemetry itself without the use of the azure monitor sdk (the call to configure_azure_monitor()). This will cause you to possibly experience duplicate telemetry entries when sending logging telemetry. Our recommendation to customers is to use solely the SDK as it will allow much more rich telemetry and features than using the built in one provided by the Azure Functions worker. You can turn off the Azure Functions telemetry logger by clearing the list of handlers of your logger.

...
root_logger = logging.getLogger()
for handler in root_logger.handlers[:]:
    root_logger.removeHandler(handler)
...

Be sure to call the above BEFORE any loggers or the call to configure_azure_monitor() is setup.

You may also disable logging through Azure Functions configuration.

v2.x+

...
{
  "logging": {
    ...
    "logLevel": {
      "default": "None",
      ...
    }
  }
}
...

v1.x

...
{
  "logger": {
    "categoryFilter": {
      "defaultLevel": "None",
      ...
    }
  }
}
...

Troubleshooting

The exporter raises exceptions defined in Azure Core.

Next steps

Check out the documentation for more.

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. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Additional documentation

• Azure Portal
• Official Azure monitor docs
• OpenTelemetry Python Official Docs