Microsoft OpenTelemetry导出器用于Azure Monitor

此导出器允许Python应用程序将OpenTelemetry SDK中的数据导出到Azure Monitor。导出器适用于需要高级配置或具有更复杂的遥测需求（需要所有分布式跟踪、日志和指标）的用户。如果您有更简单的配置需求，我们建议使用Azure Monitor OpenTelemetry Distro，它提供了一个更简单的单行设置。

在使用此SDK之前，请阅读并理解数据收集基础，特别是关于遥测类型的部分。OpenTelemetry术语与应用程序洞察术语不同，因此理解遥测类型之间的映射方式非常重要。

源代码 | 软件包（PyPi） | API参考文档 | 产品文档 | 示例 | 更新日志

入门指南

安装包

使用 pip 安装 Azure Monitor OpenTelemetry 导出器

pip install azure-monitor-opentelemetry-exporter --pre

先决条件

要使用此包，您必须具备以下条件：

• Azure 订阅 - 创建免费账户
• Azure Monitor - 如何使用应用程序洞察
• OpenTelemetry SDK - Python OpenTelemetry SDK
• Python 3.8 或更高版本 - 安装 Python

实例化客户端

与 Azure Monitor 导出器的交互从 AzureMonitorTraceExporter 类的实例开始，用于分布式跟踪，AzureMonitorLogExporter 用于记录，AzureMonitorMetricExporter 用于指标。您需要一个 连接字符串 来实例化该对象。请参考下面的示例，了解如何使用连接字符串构造导出器。

记录（实验性）

注意：目前 AzureMonitorLogExporter 的记录信号处于实验性状态。未来可能会有破坏性的更改。

from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter
exporter = AzureMonitorLogExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

指标

from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter
exporter = AzureMonitorMetricExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

跟踪

from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
exporter = AzureMonitorTraceExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

您也可以直接通过构造函数实例化导出器。在这种情况下，连接字符串将自动从 APPLICATIONINSIGHTS_CONNECTION_STRING 环境变量中填充。

from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter
exporter = AzureMonitorLogExporter()

from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter
exporter = AzureMonitorMetricExporter()

from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
exporter = AzureMonitorTraceExporter()

关键概念

Azure Monitor 导出器的关键概念包括：

• OpenTelemetry：OpenTelemetry 是一组库，用于收集和导出遥测数据（指标、日志和跟踪）以进行分析，以便了解您软件的性能和行为。

• 仪器：仪器通过允许任何应用程序直接调用 OpenTelemetry API 来提供便利。一个使另一个库具有 OpenTelemetry 可观察性的库称为仪器库。

• 日志：日志指的是记录日志、异常和事件。

• 日志记录：表示从受支持的日志库发出的日志记录。

• 日志记录器：将 LogRecord 转换为可读的 LogData，并通过 SDK 推送到导出。

• 日志记录器提供程序：为给定的仪器库提供 Logger。

• 日志记录记录处理器：用于钩子日志记录操作的接口。

• 日志处理程序：一个处理程序类，它将标准 Python logging 库中的日志记录写入 OpenTelemetry 格式。

• AzureMonitorLogExporter：这是一个初始化以向 Azure Monitor 发送与日志相关的遥测数据的类。

• 指标：指标指的是在一段时间内记录具有预定义聚合和属性集的原始测量值。

• 测量：表示在特定时间点记录的数据点。

• 仪器：仪器用于报告测量。

• 度量器：度量器负责创建仪器。

• 度量器提供者：为给定的仪表库提供度量器。

• 度量读取器：一个SDK实现对象，提供OpenTelemetry度量SDK的通用可配置方面，例如收集、刷新和关闭。

• AzureMonitorMetricExporter：这是初始化以向Azure Monitor发送度量相关遥测数据的类。

• 跟踪：跟踪指的是分布式跟踪。分布式跟踪是一组事件，由单个逻辑操作触发，跨应用程序的各个组件综合。特别是，跟踪可以被视为由Spans组成的定向无环图（DAG），其中Spans之间的边定义为父子关系。

• Span：表示跟踪内的单个操作。可以嵌套以形成跟踪树。每个跟踪包含一个根Span，它通常描述整个操作，以及可选的一个或多个子Span，用于其子操作。

• Tracer：负责创建Span。

• Tracer提供者：为给定的仪表库提供Tracer。

• Span处理器：一个Span处理器允许SDK的Span开始和结束方法调用的钩子。点击链接获取更多信息。

• AzureMonitorTraceExporter：这是初始化以向Azure Monitor发送跟踪相关遥测数据的类。

• 采样：采样是一种机制，通过减少收集和发送到后端的跟踪样本数量来控制OpenTelemetry引入的噪声和开销。

• ApplicationInsightsSampler：用于在将数据发送到Application Insights的Application Insights SDK和基于OpenTelemetry的SDK之间进行一致采样的特定于Application Insights的采样器。此采样器必须在使用AzureMonitorTraceExporter时使用。

有关这些资源的更多信息，请参阅什么是Azure Monitor？。

配置

所有配置选项都可以通过导出器的构造函数通过kwargs传递。以下是可以配置的选项列表。

• connection_string：用于您的Application Insights资源的连接字符串。
• disable_offline_storage：布尔值，用于确定是否禁用存储失败的遥测记录以进行重试。默认为False。
• storage_directory：存储目录，其中存储重试文件。默认为<tempfile.gettempdir()>/Microsoft/AzureMonitor/opentelemetry-python-<your-instrumentation-key>。
• credential：令牌凭证，例如ManagedIdentityCredential或ClientSecretCredential，用于Azure Active Directory (AAD)身份验证。默认为None。请参阅示例。

示例

记录（实验性）

注意：目前 AzureMonitorLogExporter 的记录信号处于实验性状态。未来可能会有破坏性的更改。

以下部分提供了几个代码片段，涵盖了最常见的一些任务，包括

• 导出日志记录
• 导出相关日志记录
• 导出自定义属性日志记录
• 导出异常日志记录

查阅OpenTelemetry 日志 SDK了解如何使用 OpenTelemetry 组件收集日志。

当集成 AzureMonitorLogExporter 时，强烈建议使用命名记录器而不是根记录器。这一建议源于导出器对 azure-core 的依赖，用于构建和发送请求。由于 azure-core 本身使用 Python 记录器，将处理程序附加到根记录器会意外地捕获并导出这些内部日志消息。这会触发日志和导出的递归循环，导致日志数据的不必要激增。为了避免这种情况，请为应用程序的日志需求配置命名记录器，或将日志处理程序配置为过滤来自 SDK 库的日志。

导出 Hello World 日志

"""
An example to show an application using Opentelemetry logging sdk. Logging calls to the standard Python
logging library are tracked and telemetry is exported to application insights with the AzureMonitorLogExporter.
"""
import os
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

logger_provider = LoggerProvider()
set_logger_provider(logger_provider)

exporter = AzureMonitorLogExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter))

# Attach LoggingHandler to namespaced logger
handler = LoggingHandler()
logger = logging.getLogger(__name__)
logger.addHandler(handler)
logger.setLevel(logging.NOTSET)

logger.warning("Hello World!")

# Telemetry records are flushed automatically upon application exit
# If you would like to flush records manually yourself, you can call force_flush()
logger_provider.force_flush()

导出相关日志

"""
An example showing how to include context correlation information in logging telemetry.
"""
import os
import logging

from opentelemetry import trace
from opentelemetry._logs import set_logger_provider
from opentelemetry.sdk._logs import (
    LoggerProvider,
    LoggingHandler,
)
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.sdk.trace import TracerProvider

from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter

trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)
logger_provider = LoggerProvider()
set_logger_provider(logger_provider)

exporter = AzureMonitorLogExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter))

# Attach LoggingHandler to namespaced logger
handler = LoggingHandler()
logger = logging.getLogger(__name__)
logger.addHandler(handler)
logger.setLevel(logging.NOTSET)

logger.info("INFO: Outside of span")
with tracer.start_as_current_span("foo"):
    logger.warning("WARNING: Inside of span")
logger.error("ERROR: After span")

导出自定义属性日志

"""
An example showing how to add custom properties to logging telemetry.
"""
import os
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

logger_provider = LoggerProvider()
set_logger_provider(logger_provider)

exporter = AzureMonitorLogExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter))

# Attach LoggingHandler to namespaced logger
handler = LoggingHandler()
logger = logging.getLogger(__name__)
logger.addHandler(handler)
logger.setLevel(logging.NOTSET)

# Custom properties
logger.debug("DEBUG: Debug with properties", extra={"debug": "true"})

导出异常日志

"""
An example showing how to export exception telemetry using the AzureMonitorLogExporter.
"""
import os
import logging

from opentelemetry._logs import (
    get_logger_provider,
    set_logger_provider,
)
from opentelemetry.sdk._logs import (
    LoggerProvider,
    LoggingHandler,
)
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor

from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter

set_logger_provider(LoggerProvider())
exporter = AzureMonitorLogExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
get_logger_provider().add_log_record_processor(BatchLogRecordProcessor(exporter))

# Attach LoggingHandler to namespaced logger
handler = LoggingHandler()
logger = logging.getLogger(__name__)
logger.addHandler(handler)
logger.setLevel(logging.NOTSET)

# The following code will generate two pieces of exception telemetry
# that are identical in nature
try:
    val = 1 / 0
    print(val)
except ZeroDivisionError:
    logger.exception("Error: Division by zero")

try:
    val = 1 / 0
    print(val)
except ZeroDivisionError:
    logger.error("Error: Division by zero", stack_info=True, exc_info=True)

指标

以下部分提供了几个代码片段，涵盖了最常见的一些任务，包括

• 使用不同的指标工具
• 使用视图自定义输出指标
• 使用属性记录工具

查阅OpenTelemetry 指标 SDK了解如何使用 OpenTelemetry 组件收集指标。

指标工具使用

"""
An example to show an application using all instruments in the OpenTelemetry SDK. Metrics created
and recorded using the sdk are tracked and telemetry is exported to application insights with the
AzureMonitorMetricsExporter.
"""
import os
from typing import Iterable

from opentelemetry import metrics
from opentelemetry.metrics import CallbackOptions, Observation
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader

from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter

exporter = AzureMonitorMetricExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
reader = PeriodicExportingMetricReader(exporter, export_interval_millis=5000)
metrics.set_meter_provider(MeterProvider(metric_readers=[reader]))

# Create a namespaced meter
meter = metrics.get_meter_provider().get_meter("sample")

# Callback functions for observable instruments
def observable_counter_func(options: CallbackOptions) -> Iterable[Observation]:
    yield Observation(1, {})


def observable_up_down_counter_func(
    options: CallbackOptions,
) -> Iterable[Observation]:
    yield Observation(-10, {})


def observable_gauge_func(options: CallbackOptions) -> Iterable[Observation]:
    yield Observation(9, {})

# Counter
counter = meter.create_counter("counter")
counter.add(1)

# Async Counter
observable_counter = meter.create_observable_counter(
    "observable_counter", [observable_counter_func]
)

# UpDownCounter
up_down_counter = meter.create_up_down_counter("up_down_counter")
up_down_counter.add(1)
up_down_counter.add(-5)

# Async UpDownCounter
observable_up_down_counter = meter.create_observable_up_down_counter(
    "observable_up_down_counter", [observable_up_down_counter_func]
)

# Histogram
histogram = meter.create_histogram("histogram")
histogram.record(99.9)

# Async Gauge
gauge = meter.create_observable_gauge("gauge", [observable_gauge_func])

# Upon application exit, one last collection is made and telemetry records are
# flushed automatically. # If you would like to flush records manually yourself,
# you can call force_flush()
meter_provider.force_flush()

指标自定义视图

"""
This example shows how to customize the metrics that are output by the SDK using Views. Metrics created
and recorded using the sdk are tracked and telemetry is exported to application insights with the
AzureMonitorMetricsExporter.
"""
import os

from opentelemetry import metrics
from opentelemetry.sdk.metrics import Counter, MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.metrics.view import View

from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter

exporter = AzureMonitorMetricExporter.from_connection_string(
    os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
# Create a view matching the counter instrument `my.counter`
# and configure the new name `my.counter.total` for the result metrics stream
change_metric_name_view = View(
    instrument_type=Counter,
    instrument_name="my.counter",
    name="my.counter.total",
)

reader = PeriodicExportingMetricReader(exporter, export_interval_millis=5000)
provider = MeterProvider(
    metric_readers=[
        reader,
    ],
    views=[
        change_metric_name_view,
    ],
)
metrics.set_meter_provider(provider)

meter = metrics.get_meter_provider().get_meter("view-name-change")
my_counter = meter.create_counter("my.counter")
my_counter.add(100)

有关 Views SDK 的更多示例，请访问此处。

指标记录属性

"""
An example to show an application using different attributes with instruments in the OpenTelemetry SDK.
Metrics created and recorded using the sdk are tracked and telemetry is exported to application insights
with the AzureMonitorMetricsExporter.
"""
import os

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.from_connection_string(
    os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
reader = PeriodicExportingMetricReader(exporter, export_interval_millis=5000)
metrics.set_meter_provider(MeterProvider(metric_readers=[reader]))

attribute_set1 = {
    "key1": "val1"
}
attribute_set2 = {
    "key2": "val2"
}
large_attribute_set = {}
for i in range(20):
    key = "key{}".format(i)
    val = "val{}".format(i)
    large_attribute_set[key] = val

meter = metrics.get_meter_provider().get_meter("sample")

# Counter
counter = meter.create_counter("attr1_counter")
counter.add(1, attribute_set1)

# Counter2
counter2 = meter.create_counter("attr2_counter")
counter2.add(10, attribute_set1)
counter2.add(30, attribute_set2)

# Counter3
counter3 = meter.create_counter("large_attr_counter")
counter3.add(100, attribute_set1)
counter3.add(200, large_attribute_set)

跟踪

以下部分提供了几个代码片段，涵盖了最常见的一些任务，包括

• 导出自定义跨度
• 使用工具跟踪库
• 启用采样以限制发送的遥测数据量

查阅OpenTelemetry 追踪 SDK了解如何使用 OpenTelemetry 组件收集日志。

导出 Hello World 追踪

"""
An example to show an application using Opentelemetry tracing api and sdk. Custom dependencies are
tracked via spans and telemetry is exported to application insights with the AzureMonitorTraceExporter.
"""
import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

tracer_provider = TracerProvider()
trace.set_tracer_provider(tracer_provider)
tracer = trace.get_tracer(__name__)
# This is the exporter that sends data to Application Insights
exporter = AzureMonitorTraceExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
span_processor = BatchSpanProcessor(exporter)
trace.get_tracer_provider().add_span_processor(span_processor)

with tracer.start_as_current_span("hello"):
    print("Hello, World!")

# Telemetry records are flushed automatically upon application exit
# If you would like to flush records manually yourself, you can call force_flush()
tracer_provider.force_flush()

使用请求库进行工具化

OpenTelemetry 还支持几个工具化，允许使用第三方库进行工具化。

有关 OpenTelemetry 中可用的工具化列表，请访问 contrib 文档。

此示例展示了如何使用requests库进行工具化。

• 使用 pip install opentelemetry-instrumentation-requests 安装请求工具化包。

"""
An example to show an application instrumented with the OpenTelemetry requests instrumentation.
Calls made with the requests library will be automatically tracked and telemetry is exported to 
application insights with the AzureMonitorTraceExporter.
See more info on the requests instrumentation here:
https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-requests
"""
import os
import requests
from opentelemetry import trace
from opentelemetry.instrumentation.requests import RequestsInstrumentor
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

# This line causes your calls made with the requests library to be tracked.
RequestsInstrumentor().instrument()

trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)
exporter = AzureMonitorTraceExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
span_processor = BatchSpanProcessor(exporter)
trace.get_tracer_provider().add_span_processor(span_processor)

# This request will be traced
response = requests.get(url="https://azure.microsoft.com/")

启用采样

您可以通过启用采样来限制接收的遥测记录数量。为了在 Application Insights 中启用正确的采样，请使用以下示例中的 ApplicationInsightsSampler。

"""
An example to show an application using the ApplicationInsightsSampler to enable sampling for your telemetry.
Specify a sampling rate for the sampler to limit the amount of telemetry records you receive. Custom dependencies
 are tracked via spans and telemetry is exported to application insights with the AzureMonitorTraceExporter.
"""
import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from azure.monitor.opentelemetry.exporter import (
    ApplicationInsightsSampler,
    AzureMonitorTraceExporter,
)

# Sampler expects a sample rate of between 0 and 1 inclusive
# A rate of 0.75 means approximately 75% of your telemetry will be sent
sampler = ApplicationInsightsSampler(0.75)
trace.set_tracer_provider(TracerProvider(sampler=sampler))
tracer = trace.get_tracer(__name__)
exporter = AzureMonitorTraceExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
span_processor = BatchSpanProcessor(exporter)
trace.get_tracer_provider().add_span_processor(span_processor)

for i in range(100):
    # Approximately 25% of these spans should be sampled out
    with tracer.start_as_current_span("hello"):
        print("Hello, World!")

刷新/关闭行为

对于所有使用 OpenTelemetry SDK 和 Azure Monitor 导出器设置的应用程序，在应用程序退出时会自动刷新遥测数据。请注意，这不包括由于意外终止或未捕获的异常导致的程序崩溃。

故障排除

导出器会引发在Azure Core中定义的异常。

下一步

更多示例代码

请参阅示例目录中的更多示例，这些示例展示了常见场景。

附加文档

有关 Azure Monitor 服务的更全面文档，请参阅 docs.microsoft.com 上的Azure Monitor 文档。

有关 OpenTelemetry 的详细概述，请访问他们的概述页面。

有关官方 OpenTelemetry Python 文档以及如何启用其他遥测场景，请访问官方 OpenTelemetry 网站。

有关Azure Monitor OpenTelemetry Distro的更多信息，这是一个包含有用、预先组装的组件（其中之一就是当前这个包）的捆绑包，它使您能够使用Azure Monitor进行遥测，请访问README。

贡献

本项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议（CLA），声明您有权，并且实际上确实授予我们使用您贡献的权利。有关详细信息，请访问https://cla.microsoft.com。

当您提交拉取请求时，CLA机器人将自动确定您是否需要提供CLA，并相应地装饰PR（例如，标签、注释）。只需遵循机器人提供的说明即可。您只需要在整个使用我们CLA的仓库中这样做一次。

本项目已采用Microsoft Open Source Code of Conduct。有关更多信息，请参阅Code of Conduct FAQ或通过opencode@microsoft.com联系以获取任何额外的问题或评论。