Registry /
azure / azure-monitor-opentelemetry
Install & Compatibility
Where this runs
tested against v1.8.9 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.802s · 56.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.6s · import 1.656s · 57MB
56MB installed
● package 56MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
configure_azure_monitor
✓ from azure.monitor.opentelemetry import configure_azure_monitor
This quickstart demonstrates how to initialize the Azure Monitor OpenTelemetry Distro. Ensure the `APPLICATIONINSIGHTS_CONNECTION_STRING` environment variable is set with your Azure Application Insights connection string. The `configure_azure_monitor()` function automatically sets up the necessary OpenTelemetry components. A simple custom span is created to illustrate basic tracing.
import os
from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace
# Set your Application Insights Connection String as an environment variable:
# APPLICATIONINSIGHTS_CONNECTION_STRING="InstrumentationKey=YOUR_INSTRUMENTATION_KEY;IngestionEndpoint=https://YOUR_REGION.in.applicationinsights.azure.com/"
# One-line setup - reads connection string from the environment variable
# APPLICATIONINSIGHTS_CONNECTION_STRING. Call this early in your application.
configure_azure_monitor()
# Get a tracer from OpenTelemetry
tracer = trace.get_tracer(__name__)
# Create a sample span
with tracer.start_as_current_span("my-example-span"):
print("Hello from an OpenTelemetry-instrumented application!")
# Simulate some work
import time
time.sleep(0.1)
print("Telemetry sent to Azure Monitor (if connection string is configured).")
Debug
Known issues
breakingMigration from older Application Insights SDKs (2.x) to `azure-monitor-opentelemetry` requires significant code changes, as most 2.x APIs are not supported and need to be updated to OpenTelemetry-based APIs.fixReview the official migration guide on Microsoft Learn to adapt your code to OpenTelemetry-based APIs.
affects: All versions when migrating from Application Insights SDK 2.x
breakingMany OpenTelemetry instrumentations bundled with this distro are currently in a beta state, meaning they are not stable and may introduce breaking changes in future releases.fixMonitor release notes and be prepared for potential breaking changes in minor or patch versions, especially when OpenTelemetry specifications evolve.
affects: All current versions (1.x.x)
gotchaThe `configure_azure_monitor()` function must be called early in your application's lifecycle, preferably before importing other instrumented libraries, to ensure all telemetry is captured correctly and avoid potential data loss.fixPlace `configure_azure_monitor()` at the very beginning of your application's entry point script.
affects: All versions
gotchaEnabling both native logging instrumentation in Azure Functions and `azure-monitor-opentelemetry` logging instrumentation within the distribution can lead to duplicate trace logs in Application Insights.fixDisable one of the logging instrumentations to avoid duplicate telemetry. Refer to troubleshooting guides for specific configurations.
affects: All versions when used in Azure Functions
gotchaDependency telemetry might occasionally be missing the 'operation name' or 'device model', which can adversely affect performance analysis, filtering, and device cohort analysis in Application Insights.fixCheck for updates to the library or OpenTelemetry instrumentations. Manually add these attributes if critical for your analysis.
affects: All versions
breakingThe `azure-monitor-opentelemetry` library requires a valid Azure Monitor Connection String or Instrumentation Key to be configured. This can be provided via the `APPLICATIONINSIGHTS_CONNECTION_STRING` environment variable, `APPINSIGHTS_INSTRUMENTATIONKEY` environment variable, or as an argument to `configure_azure_monitor()`. Failure to provide this will result in a `ValueError`.fixSet the `APPLICATIONINSIGHTS_CONNECTION_STRING` or `APPINSIGHTS_INSTRUMENTATIONKEY` environment variable, or pass a `connection_string` argument to `configure_azure_monitor()`. Refer to the official documentation for setup instructions.
affects: All versions
breakingThe `configure_azure_monitor()` function requires a valid Azure Monitor Connection String (or Instrumentation Key) to be provided, either directly as an argument or via the `APPLICATIONINSIGHTS_CONNECTION_STRING` environment variable. Without this, telemetry cannot be exported, and a `ValueError` will be raised.fixEnsure the `APPLICATIONINSIGHTS_CONNECTION_STRING` environment variable is set with a valid connection string, or pass the `connection_string` argument directly to `configure_azure_monitor()`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'azure.monitor.opentelemetry'
The `azure-monitor-opentelemetry` package or one of its dependencies is not installed in the Python environment.
fixInstall the package using pip: `pip install azure-monitor-opentelemetry`
Failed to send telemetry with status code: 403, please check your credentials.
Telemetry (traces, metrics, or logs) not appearing in Azure Monitor/Application Insights.
This can be caused by an incorrect or missing connection string, network connectivity issues to the ingestion service, misconfigured sampling, or duplicate telemetry due to multiple instrumentation sources.
fix1. Ensure the `APPLICATIONINSIGHTS_CONNECTION_STRING` is correctly set and valid. 2. Check network connectivity from the application host to Azure ingestion endpoints. 3. Enable diagnostic logging for `azure-monitor-opentelemetry` to identify specific errors. 4. Review sampling configurations to ensure telemetry isn't being excessively dropped. 5. Avoid duplicate telemetry by ensuring only one instrumentation source is active for each telemetry type (e.g., if using `configure_azure_monitor`, disable native logging instrumentation in Azure Functions).
Duplicate logging entries in Azure Functions when using azure-monitor-opentelemetry.
In Azure Functions, both the native Functions worker and the `azure-monitor-opentelemetry` SDK might be sending logging telemetry, leading to duplicate entries.
fixAfter calling `configure_azure_monitor()`, clear the handlers of the root logger to prevent the Azure Functions' built-in telemetry logger from sending duplicate logs: `import logging; root_logger = logging.getLogger(); for handler in root_logger.handlers: root_logger.removeHandler(handler)`
Upgrade
Version history
1.8.9latest on PyPI · released Jul 1, 2026
Audit
Dependencies
azure-monitor-opentelemetry-exporterrequiredAutomatically installed and used for exporting telemetry to Azure Monitor.
opentelemetry-instrumentation-requestsoptionalAutomatically installed for HTTP/HTTPS request instrumentation.
opentelemetry-instrumentation-djangooptionalAutomatically installed for Django framework instrumentation.
opentelemetry-instrumentation-flaskoptionalAutomatically installed for Flask framework instrumentation.
opentelemetry-instrumentation-psycopg2optionalAutomatically installed for Psycopg2 (PostgreSQL) database instrumentation.
opentelemetry-instrumentation-urlliboptionalAutomatically installed for urllib library instrumentation.
opentelemetry-instrumentation-urllib3optionalAutomatically installed for urllib3 library instrumentation.
azure-core-tracing-opentelemetryoptionalAutomatically installed for Azure SDK tracing.