Azure Monitor Opentelemetry Distro client library for Python

The Azure Monitor Distro of [Opentelemetry Python][ot_sdk_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][azure_monitor_opentelemetry_exporters] and reports telemetry to Azure Monitor via the [Azure Monitor exporters][azure_monitor_opentelemetry_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][azure_monitor_opentelemetry_exporters]
• A subset of OpenTelemetry [instrumentations][ot_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.

Instrumentation	Supported library Name	Supported versions
[Azure Core Tracing OpenTelemetry][azure_core_tracing_opentelemetry_plugin]	azure_sdk
[OpenTelemetry Django Instrumentation][ot_instrumentation_django]	[django][pypi_django]	[link][ot_instrumentation_django_version]
[OpenTelemetry FastApi Instrumentation][ot_instrumentation_fastapi]	[fastapi][pypi_fastapi]	[link][ot_instrumentation_fastapi_version]
[OpenTelemetry Flask Instrumentation][ot_instrumentation_flask]	[flask][pypi_flask]	[link][ot_instrumentation_flask_version]
[OpenTelemetry Psycopg2 Instrumentation][ot_instrumentation_psycopg2]	[psycopg2][pypi_psycopg2]	[link][ot_instrumentation_psycopg2_version]
[OpenTelemetry Requests Instrumentation][ot_instrumentation_requests]	[requests][pypi_requests]	[link][ot_instrumentation_requests_version]
[OpenTelemetry UrlLib Instrumentation][ot_instrumentation_urllib]	[urllib][pypi_urllib]	All
[OpenTelemetry UrlLib3 Instrumentation][ot_instrumentation_urllib3]	[urllib3][pypi_urllib3]	[link][ot_instrumentation_urllib3_version]

If you would like to add support for another OpenTelemetry instrumentation, please submit a feature [request][distro_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][samples_manual] 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][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_sub]
• Azure Monitor - [How to use application insights][application_insights_namespace]
• Opentelemetry SDK - [Opentelemetry SDK for Python][ot_sdk_python]
• Python 3.9 or later - [Install Python][python]

Install the package

Install the Azure Monitor Opentelemetry Distro with [pip][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.

Parameter	Description	Environment Variable
connection_string	The [connection string][connection_string_doc] for your Application Insights resource. The connection string will be automatically populated from the APPLICATIONINSIGHTS_CONNECTION_STRING environment variable if not explicitly passed in.	APPLICATIONINSIGHTS_CONNECTION_STRING
enable_live_metrics	Enable [live metrics][application_insights_live_metrics] feature. Defaults to True.	N/A
enable_performance_counters	Enable [performance counters][application_insights_performance_counters]. Defaults to True.	N/A
logging_formatter	A Python logging [formatter][python_logging_formatter] that will be used to format collected logs.	PYTHON_APPLICATIONINSIGHTS_LOGGING_FORMAT - accepts a STRING field used for formatting, not a [formatter][python_logging_formatter]
logger_name	The name of the [Python logger][python_logger] under which telemetry is collected. Setting this value is imperative so logs created from the SDK itself are not tracked.	PYTHON_APPLICATIONINSIGHTS_LOGGER_NAME
instrumentation_options	A nested dictionary that determines which instrumentations to enable or disable. Instrumentations are referred to by their Library Names. For example, {"azure_sdk": {"enabled": False}, "flask": {"enabled": False}, "django": {"enabled": True}} will disable Azure Core Tracing and the Flask instrumentation but leave Django and the other default instrumentations enabled. The OTEL_PYTHON_DISABLED_INSTRUMENTATIONS environment variable explained below can also be used to disable instrumentations.	N/A
resource	Specifies the OpenTelemetry [Resource][ot_spec_resource] associated with your application. Passed in [Resource Attributes][ot_spec_resource_attributes] take priority over default attributes and those from [Resource Detectors][ot_python_resource_detectors].	[OTEL_SERVICE_NAME][ot_spec_service_name], [OTEL_RESOURCE_ATTRIBUTES][ot_spec_resource_attributes], [OTEL_EXPERIMENTAL_RESOURCE_DETECTORS][ot_python_resource_detectors]
span_processors	A list of [span processors][ot_span_processor] that will perform processing on each of your spans before they are exported. Useful for filtering/modifying telemetry.	N/A
views	A list of [views][ot_view] that will be used to customize metrics exported by the SDK.	N/A
log_record_processors	A list of [log record processors][ot_log_record_processor] that will process log records before they are exported.	N/A
metric_readers	A list of [metric reader][ot_metric_reader] that will process metric readers before they are exported	N/A
sampling_ratio	Configures the Application Insights Sampler specifying the percentage of traces to be sampled. Has to be a value between 0 and 1. For example, 0.1 sampling ratio would mean sampling 10% of all the traces. Defaults to 1.0 i.e 100% sampling rate. Please note that the sampling configuration via environment variables will have precedence over the sampling exporter/distro options.	N/A
traces_per_second	Configures the Rate Limited Sampler by specifying the maximum number of traces to sample per second. When set, this automatically enables the rate-limited sampler. Alternatively, you can configure sampling using the OTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG environment variables as described in the table below. To switch back to fixed percentage sampler, set the sampling_ratio to the desired value, ex. 1.0. Please refer to [sampling_configurations] sample file for more clarity on sampler configuration. Please note that the sampling configuration via environment variables will have precedence over the sampling exporter/distro options.	N/A

You can configure further with [OpenTelemetry environment variables][ot_env_vars].

Environment Variable	Description
[OTEL_SERVICE_NAME][ot_spec_service_name], [OTEL_RESOURCE_ATTRIBUTES][ot_spec_resource_attributes]	Specifies the OpenTelemetry [Resource][ot_spec_resource] associated with your application.
OTEL_LOGS_EXPORTER	If set to None, disables collection and export of logging telemetry.
OTEL_METRICS_EXPORTER	If set to None, disables collection and export of metric telemetry.
OTEL_TRACES_EXPORTER	If set to None, disables collection and export of distributed tracing telemetry.
OTEL_BLRP_SCHEDULE_DELAY	Specifies the logging export interval in milliseconds. Defaults to 5000.
OTEL_BSP_SCHEDULE_DELAY	Specifies the distributed tracing export interval in milliseconds. Defaults to 5000.
OTEL_TRACES_SAMPLER	Specifies the sampler to be used for traces. Supports always_on, always_off, trace_id_ratio, parentbased_always_on, parentbased_always_off, parentbased_trace_id_ratio, [application_insights_sampling] and [rate_limited_sampling]. Use microsoft.fixed_percentage for the Application Insights sampler or microsoft.rate_limited for the Rate Limited sampler. The default sampler is Rate Limited Sampler with the default value of 5.0 traces per second
OTEL_TRACES_SAMPLER_ARG	Spec