---
name: azure-monitor-opentelemetry-py
description: |
Azure Monitor OpenTelemetry Distro for Python. Use for one-line Application Insights setup with auto-instrumentation.
Triggers: "azure-monitor-opentelemetry", "configure_azure_monitor", "Application Insights", "OpenTelemetry distro", "auto-instrumentation".
license: MIT
metadata:
author: Microsoft
version: "1.0.0"
package: azure-monitor-opentelemetry
---
# 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 Configuration
```python
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
```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. 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
| 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. |