azure-monitor-opentelemetry-py

# 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](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | | [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. |