Azure Monitor OpenTelemetry Distro for Python

Common errors

• ModuleNotFoundError: No module named 'azure.monitor.opentelemetry'

  cause The `azure-monitor-opentelemetry` package or one of its dependencies is not installed in the Python environment.
  fix Install the package using pip: `pip install azure-monitor-opentelemetry`

• Failed to send telemetry with status code: 403, please check your credentials.

• 401 Unauthorized

• Telemetry (traces, metrics, or logs) not appearing in Azure Monitor/Application Insights.

  cause 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.
  fix 1. 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.

  cause In Azure Functions, both the native Functions worker and the `azure-monitor-opentelemetry` SDK might be sending logging telemetry, leading to duplicate entries.
  fix After 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)`

Warnings

• breaking Migration 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.
  Fix: Review the official migration guide on Microsoft Learn to adapt your code to OpenTelemetry-based APIs.
• breaking Many 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.
  Fix: Monitor release notes and be prepared for potential breaking changes in minor or patch versions, especially when OpenTelemetry specifications evolve.
• gotcha The `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.
  Fix: Place `configure_azure_monitor()` at the very beginning of your application's entry point script.
• gotcha Enabling 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.
  Fix: Disable one of the logging instrumentations to avoid duplicate telemetry. Refer to troubleshooting guides for specific configurations.
• gotcha Dependency 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.
  Fix: Check for updates to the library or OpenTelemetry instrumentations. Manually add these attributes if critical for your analysis.
• breaking The `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`.
  Fix: Set 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.
• breaking The `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.
  Fix: Ensure the `APPLICATIONINSIGHTS_CONNECTION_STRING` environment variable is set with a valid connection string, or pass the `connection_string` argument directly to `configure_azure_monitor()`.

Install

• pip install azure-monitor-opentelemetry Install stable version

Imports

• configure_azure_monitor

  from azure.monitor.opentelemetry import configure_azure_monitor

Quickstart

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).")