Azure Monitor OpenTelemetry Distro for Python

One-line setup for Application Insights with OpenTelemetry auto-instrumentation.

Installation

bash
pip install azure-monitor-opentelemetry

Environment Variables

bash
APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=xxx;IngestionEndpoint=https://xxx.in.applicationinsights.azure.com/  # Required for all auth methods
AZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production

Authentication & Lifecycle

> 🔑 Two rules apply to every code sample below: > > 1. Prefer DefaultAzureCredential for ingestion auth when supported. APPLICATIONINSIGHTS_CONNECTION_STRING identifies the target Application Insights resource, and credential=DefaultAzureCredential(...) provides Microsoft Entra authentication. > - Local dev: DefaultAzureCredential works as-is. > - Production: set AZURE_TOKEN_CREDENTIALS=prod (or AZURE_TOKEN_CREDENTIALS=<specific_credential>) to constrain the credential chain to production-safe credentials. > 2. Providers are not context managers. Flush and shut down telemetry providers explicitly at process exit so buffers are exported deterministically. > > Snippets may abbreviate this setup, but production code should always follow both rules.

Quick Start

python
from azure.identity import DefaultAzureCredential
from azure.monitor.opentelemetry import configure_azure_monitor

# Connection string identifies the App Insights resource (read from APPLICATIONINSIGHTS_CONNECTION_STRING env var).
# DefaultAzureCredential authenticates ingestion via Microsoft Entra ID (preferred over instrumentation-key-only auth).
configure_azure_monitor(
    credential=DefaultAzureCredential(),
)

# Your application code...

Explicit Connection String

Pass the connection string explicitly by reading it from the environment variable. The value includes both InstrumentationKey and IngestionEndpoint.

python
import os
from azure.monitor.opentelemetry import configure_azure_monitor

# Read the full connection string from the environment.
# Format: "InstrumentationKey=<key>;IngestionEndpoint=https://<id>.in.applicationinsights.azure.com/"
connection_string = os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]

try:
    configure_azure_monitor(
        connection_string=connection_string,
    )
    # Your application code...
except Exception as exc:
    raise RuntimeError(f"Azure Monitor configuration failed: {exc}") from exc

With Flask

python
from flask import Flask
from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor()

app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello, World!"

if __name__ == "__main__":
    app.run()

With Django

python
# settings.py
from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor()

# Django settings...

With FastAPI

python
from fastapi import FastAPI
from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor()

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

Custom Traces

python
from opentelemetry import trace
from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor()

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("my-operation") as span:
    span.set_attribute("custom.attribute", "value")
    # Do work...

Custom Metrics

python
from opentelemetry import metrics
from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor()

meter = metrics.get_meter(__name__)
counter = meter.create_counter("my_counter")

counter.add(1, {"dimension": "value"})

Custom Logs

python
import logging
from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor()

logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)

logger.info("This will appear in Application Insights")
logger.error("Errors are captured too", exc_info=True)

Sampling

python
from azure.monitor.opentelemetry import configure_azure_monitor

# Sample 10% of requests
configure_azure_monitor(
    sampling_ratio=0.1
)

Cloud Role Name

Set cloud role name for Application Map:

python
from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry.sdk.resources import Resource, SERVICE_NAME

configure_azure_monitor(
    resource=Resource.create({SERVICE_NAME: "my-service-name"})
)

Disable Specific Instrumentations

python
from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
    instrumentations=["flask", "requests"]  # Only enable these
)

Enable Live Metrics

python
from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
    enable_live_metrics=True
)

Azure AD Authentication

python
from azure.monitor.opentelemetry import configure_azure_monitor
from azure.identity import DefaultAzureCredential, ManagedIdentityCredential

# Local dev: DefaultAzureCredential. In production, set AZURE_TOKEN_CREDENTIALS=prod or use a specific credential.
credential = DefaultAzureCredential()
# Or use a specific credential directly in production:
# See https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes
# credential = ManagedIdentityCredential()

configure_azure_monitor(
    credential=credential
)

Auto-Instrumentations Included

| Library | Telemetry Type | |---------|---------------| | Flask | Traces | | Django | Traces | | FastAPI | Traces | | Requests | Traces | | urllib3 | Traces | | httpx | Traces | | aiohttp | Traces | | psycopg2 | Traces | | pymysql | Traces | | pymongo | Traces | | redis | Traces |

Configuration Options

| Parameter | Description | Default | |-----------|-------------|---------| | connection_string | Application Insights connection string | From env var | | credential | Azure credential for AAD auth | None | | sampling_ratio | Sampling rate (0.0 to 1.0) | 1.0 | | resource | OpenTelemetry Resource | Auto-detected | | instrumentations | List of instrumentations to enable | All | | enable_live_metrics | Enable Live Metrics stream | False |

Best Practices

1. Pick sync OR async and stay consistent. Do not mix azure.xxx sync clients with azure.xxx.aio async clients in the same call path. Choose one mode per module.
2. Call provider.shutdown() / force_flush() at process exit to flush telemetry — providers are not context managers.
3. Call configure_azure_monitor() early — Before importing instrumented libraries
4. Use environment variables for connection string in production
5. Set cloud role name for multi-service applications
6. Enable sampling in high-traffic applications
7. Use structured logging for better log analytics queries
8. Add custom attributes to spans for better debugging
9. Use Microsoft Entra authentication for production workloads

Reference Files

| File | Contents | |------|----------| | references/capabilities.md | Additional non-hero capabilities, operation-group coverage, and production checklists. | | references/non-hero-scenarios.md | Dedicated non-hero examples for secondary/advanced scenarios. |