azure-monitor-opentelemetry-py

用于 Python 的 Azure Monitor OpenTelemetry 发行版

一行即可为 Application Insights 配置 OpenTelemetry 自动检测。

安装

pip install azure-monitor-opentelemetry

环境变量

APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=xxx;IngestionEndpoint=https://xxx.in.applicationinsights.azure.com/

快速入门

from azure.monitor.opentelemetry import configure_azure_monitor

# One-line setup - reads connection string from environment
configure_azure_monitor()

# Your application code...

显式配置

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
    connection_string="InstrumentationKey=xxx;IngestionEndpoint=https://xxx.in.applicationinsights.azure.com/"
)

使用 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()

使用 Django

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

configure_azure_monitor()

# Django settings...

使用 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"}

自定义跟踪

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

自定义指标

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

自定义日志

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)

采样

from azure.monitor.opentelemetry import configure_azure_monitor

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

云角色名称

为 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"})
)

禁用特定检测

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
    instrumentation_options={"flask": {"enabled": False}}  # Disable Flask; others keep defaults
)

启用 Live Metrics

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
    enable_live_metrics=True
)

Azure AD 身份验证

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

configure_azure_monitor(
    credential=DefaultAzureCredential()
)

每个进程只配置一次。固定并检查已安装的发行版：受支持的库和默认值会发生变化，而且 Azure Monitor 与 Microsoft OpenTelemetry 发行版使用不同的 API。不要同时初始化两者。Azure SDK 参考介绍了 instrumentation_options；请确认可选检测项及其依赖项，不要假设下面列出的每个库都已包含在内。遥测数据会离开进程：请授权其目标位置和保留期限，从日志和跨度中删除机密及个人数据，限制基数和数据摄取成本，并使用合成数据验证导出。跟踪采样并不意味着指标或所有日志也会被采样。

包含的自动检测

库	遥测类型
Flask	跟踪
Django	跟踪
FastAPI	跟踪
Requests	跟踪
urllib3	跟踪
httpx	跟踪
aiohttp	跟踪
psycopg2	跟踪
pymysql	跟踪
pymongo	跟踪
redis	跟踪

配置选项

参数	说明	默认值
connection_string	Application Insights 连接字符串	来自环境变量
credential	用于 AAD 身份验证的 Azure 凭据	无
sampling_ratio	显式跟踪采样比例	取决于版本；请检查采样器和环境
resource	OpenTelemetry 资源	自动检测
instrumentation_options	按库设置的启用状态字典	默认值取决于版本
enable_live_metrics	启用 Live Metrics 流	取决于版本；请显式设置

最佳实践

1. 尽早调用 configure_azure_monitor() — 在导入经过检测的库之前
2. 在生产环境中使用环境变量设置连接字符串
3. 为多服务应用程序设置云角色名称
4. 在高流量应用程序中启用采样
5. 使用结构化日志，以便更好地查询日志分析
6. 向跨度添加自定义属性，以便更好地进行调试
7. 在生产工作负载中使用 AAD 身份验证

适用场景

当任务涉及执行概述中描述的工作流或操作时，可使用此技能。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 请勿将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少所需输入、权限、安全边界或成功标准，请停止并请求澄清。