azure-monitor-opentelemetry-py

Einzeilige Einrichtung für Application Insights mit OpenTelemetry-Autoinstrumentierung.

npx skills add https://github.com/microsoft/skills --skill azure-monitor-opentelemetry-py

Azure Monitor OpenTelemetry Distro for Python

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

Installation

pip install azure-monitor-opentelemetry

Environment Variables

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

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 Configuration

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

# Reads APPLICATIONINSIGHTS_CONNECTION_STRING from env to identify the resource;
# DefaultAzureCredential authenticates ingestion via Microsoft Entra ID.
configure_azure_monitor(
    credential=DefaultAzureCredential(),
)

With Flask

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

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

configure_azure_monitor()

# Django settings...

With FastAPI

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

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

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

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

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:

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

from azure.monitor.opentelemetry import configure_azure_monitor

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

Enable Live Metrics

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
    enable_live_metrics=True
)

Azure AD Authentication

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

# Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
credential = DefaultAzureCredential(require_envvar=True)
# 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

LibraryTelemetry Type
FlaskTraces
DjangoTraces
FastAPITraces
RequestsTraces
urllib3Traces
httpxTraces
aiohttpTraces
psycopg2Traces
pymysqlTraces
pymongoTraces
redisTraces

Configuration Options

ParameterDescriptionDefault
connection_stringApplication Insights connection stringFrom env var
credentialAzure credential for AAD authNone
sampling_ratioSampling rate (0.0 to 1.0)1.0
resourceOpenTelemetry ResourceAuto-detected
instrumentationsList of instrumentations to enableAll
enable_live_metricsEnable Live Metrics streamFalse

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

FileContents
references/capabilities.mdAdditional non-hero capabilities, operation-group coverage, and production checklists.
references/non-hero-scenarios.mdDedicated non-hero examples for secondary/advanced scenarios.