Azure Monitor OpenTelemetry Python 导出器

azure-monitor-opentelemetry-exporter-py
分类编程
作者Agentic Awesome Skills 社区
许可MIT
评分4.80/5
使用7.7K

Azure Monitor OpenTelemetry Exporter for Python

用于将 OpenTelemetry 追踪 (traces)、指标 (metrics) 和日志 (logs) 发送到 Application Insights 的低级别导出器。

安装

bash
pip install azure-monitor-opentelemetry-exporter

环境变量

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

使用场景

| 场景 | 推荐使用 | |----------|-----| | 快速设置，自动注入 | azure-monitor-opentelemetry (发行版) | | 自定义 OpenTelemetry 流水线 | azure-monitor-opentelemetry-exporter (本库) | | 对遥测数据进行精细化控制 | azure-monitor-opentelemetry-exporter (本库) |

追踪导出器 (Trace Exporter)

python
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

创建导出器

exporter = AzureMonitorTraceExporter(
    connection_string="InstrumentationKey=xxx;..."
)

配置 tracer provider

trace.set_tracer_provider(TracerProvider())
trace.get_tracer_provider().add_span_processor(
    BatchSpanProcessor(exporter)
)

使用 tracer

tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("my-span"):
    print("Hello, World!")

指标导出器 (Metric Exporter)

python
from opentelemetry import metrics
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter

创建导出器

exporter = AzureMonitorMetricExporter(
    connection_string="InstrumentationKey=xxx;..."
)

配置 meter provider

reader = PeriodicExportingMetricReader(exporter, export_interval_millis=60000)
metrics.set_meter_provider(MeterProvider(metric_readers=[reader]))

使用 meter

meter = metrics.get_meter(__name__)
counter = meter.create_counter("requests_total")
counter.add(1, {"route": "/api/users"})

日志导出器 (Log Exporter)

python
import logging
from opentelemetry._logs import set_logger_provider
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter

创建导出器

exporter = AzureMonitorLogExporter(
    connection_string="InstrumentationKey=xxx;..."
)

配置 logger provider

logger_provider = LoggerProvider()
logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter))
set_logger_provider(logger_provider)

将 handler 添加到 Python logging

handler = LoggingHandler(level=logging.INFO, logger_provider=logger_provider)
logging.getLogger().addHandler(handler)

使用 logging

logger = logging.getLogger(__name__)
logger.info("This will be sent to Application Insights")

通过环境变量配置

导出器会自动读取 APPLICATIONINSIGHTS_CONNECTION_STRING：

python
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

从环境变量读取连接字符串

exporter = AzureMonitorTraceExporter()

Azure AD 身份验证

python
from azure.identity import DefaultAzureCredential
from azure.monitor.ope
python
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

exporter = AzureMonitorTraceExporter(
    credential=DefaultAzureCredential()
)

采样 (Sampling)

使用 ApplicationInsightsSampler 实现一致的采样：

python
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.sampling import ParentBasedTraceIdRatio
from azure.monitor.opentelemetry.exporter import ApplicationInsightsSampler

采样 10% 的追踪数据

sampler = ApplicationInsightsSampler(sampling_ratio=0.1)

trace.set_tracer_provider(TracerProvider(sampler=sampler))

离线存储 (Offline Storage)

配置离线存储以支持重试：

python
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

exporter = AzureMonitorTraceExporter(
    connection_string="...",
    storage_directory="/path/to/storage",  # 自定义存储路径
    disable_offline_storage=False  # 启用重试（默认）
)

禁用离线存储

python
exporter = AzureMonitorTraceExporter(
    connection_string="...",
    disable_offline_storage=True  # 失败时不重试
)

主权云 (Sovereign Clouds)

python
from azure.identity import AzureAuthorityHosts, DefaultAzureCredential
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

Azure Government

credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
exporter = AzureMonitorTraceExporter(
    connection_string="InstrumentationKey=xxx;IngestionEndpoint=https://xxx.in.applicationinsights.azure.us/",
    credential=credential
)

导出器类型 (Exporter Types)

| 导出器 | 遥测类型 | Application Insights 表 |
|----------|---------------|---------------------------|
| AzureMonitorTraceExporter | Traces/Spans | requests, dependencies, exceptions |
| AzureMonitorMetricExporter | Metrics | customMetrics, performanceCounters |
| AzureMonitorLogExporter | Logs | traces, customEvents |

配置选项 (Configuration Options)

| 参数 | 描述 | 默认值 |
|-----------|-------------|---------|
| connection_string | Application Insights 连接字符串 | 来自环境变量 |
| credential | 用于 AAD 认证的 Azure 凭据 | None |
| disable_offline_storage | 禁用重试存储 | False |
| storage_directory | 自定义存储路径 | 临时目录 |

最佳实践

1. 生产环境请使用 BatchSpanProcessor（而非 SimpleSpanProcessor）。
2. 使用 ApplicationInsightsSampler 以确保跨服务采样的一致性。
3. 在生产环境中 启用离线存储 以提高可靠性。
4. 优先使用 AAD 身份验证 而非 instrumentation keys。
5. 根据工作负载 设置合适的导出间隔。
6. 除非需要自定义流水线，否则请直接使用 发行版 (azure-monitor-opentelemetry)。

局限性

  • 仅在任务明确符合上述范围时使用此技能。
  • 不要将输出视为针对特定环境的验证、测试或专家评审的替代方案。
  • 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。