Azure Monitor Opentelemetry Distro Python客户端库

Azure Monitor版的Opentelemetry Python是一个“一站式”遥测解决方案，只需一行代码即可对你的应用程序进行性能监控。该版本通过OpenTelemetry性能监控捕获遥测数据，并通过Azure Monitor性能监控导出器将遥测数据发送到Azure Monitor。

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

此版本自动安装以下库

• Azure Monitor OpenTelemetry导出器
• 以下列出的官方支持的OpenTelemetry性能监控子集。

官方支持的性能监控

OpenTelemetry性能监控允许自动收集从底层性能监控库发送的请求。以下是在Azure Monitor版本中捆绑的OpenTelemetry性能监控列表。默认情况下，这些性能监控已启用。有关如何取消这些性能监控的启用，请参阅下面的使用部分。

如果您想添加对其他OpenTelemetry性能监控的支持，请提交一个功能请求。在此期间，您可以通过自己的API（即instrument()）在代码中手动使用OpenTelemetry性能监控。请参阅此示例。

关键概念

此软件包捆绑了一系列OpenTelemetry和Azure Monitor组件，以实现将遥测数据收集并发送到Azure Monitor。对于MANUAL性能监控，请使用configure_azure_monitor函数。目前尚不支持AUTOMATIC性能监控。

Azure Monitor OpenTelemetry导出器是完成此任务的主要组件。您可以通过此软件包直接使用导出器和它们的API。请参阅导出器文档，了解OpenTelemetry和Azure Monitor组件如何协同工作以启用遥测数据的收集和导出。

目前，OpenTelemetry中所有可用的性能监控都处于beta状态，这意味着它们并不稳定，未来可能会有破坏性的更改。正在努力将这些性能监控推向更稳定的状态。

入门

先决条件

要使用此软件包，您必须具备

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

安装软件包

使用pip安装Azure Monitor OpenTelemetry版本

pip install azure-monitor-opentelemetry

使用

您可以使用 configure_azure_monitor 为您的应用程序设置 Azure Monitor 的监控。 configure_azure_monitor 支持以下可选参数。所有传入参数的优先级高于任何相关环境变量。

您还可以使用 OpenTelemetry 环境变量 进行进一步配置。

Azure 监控 OpenTelemetry 导出器配置

您可以直接将 Azure 监控 OpenTelemetry 导出器配置参数传递给 configure_azure_monitor。有关更多导出配置相关信息。

...
configure_azure_monitor(
   connection_string="<your-connection-string>",
   disable_offline_storage=True,
)
...

示例

示例在此处可用，以展示如何使用上述配置选项。

Azure Functions 中的监控

跟踪关联

追踪进入您在 Azure Functions 中托管的 Python 应用程序中的传入请求将不会自动与内部跟踪的遥测关联。您可以通过以下方式手动实现跟踪关联：直接提取 TraceContext，如下所示

import azure.functions as func

from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace
from opentelemetry.propagate import extract

# Configure Azure monitor collection telemetry pipeline
configure_azure_monitor()

def main(req: func.HttpRequest, context) -> func.HttpResponse:
   ...
   # Store current TraceContext in dictionary format
   carrier = {
      "traceparent": context.trace_context.Traceparent,
      "tracestate": context.trace_context.Tracestate,
   }
   tracer = trace.get_tracer(__name__)
   # Start a span using the current context
   with tracer.start_as_current_span(
      "http_trigger_span",
      context=extract(carrier),
   ):
      ...

记录问题

Azure Functions 工作进程本身会发送遥测，而无需使用 azure 监控 SDK（调用 configure_azure_monitor()）。这可能导致在发送记录遥测时出现重复的遥测条目。我们向客户推荐仅使用 SDK，因为它将允许比使用 Azure Functions 工作进程提供的内置遥测更丰富遥测和功能。您可以通过清除您的记录器处理程序列表来关闭 Azure Functions 遥测记录器。

...
root_logger = logging.getLogger()
for handler in root_logger.handlers[:]:
    root_logger.removeHandler(handler)
...

请确保在设置任何记录器或调用 configure_azure_monitor() 之前调用以上操作。

您还可以通过Azure Functions 配置禁用记录。

v2.x+

...
{
  "logging": {
    ...
    "logLevel": {
      "default": "None",
      ...
    }
  }
}
...

v1.x

...
{
  "logger": {
    "categoryFilter": {
      "defaultLevel": "None",
      ...
    }
  }
}
...

故障排除

导出器抛出在 Azure Core 中定义的异常。

下一步

查看文档以获取更多信息。

贡献

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

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

本项目采用了微软开源行为准则。如需更多信息，请参阅行为准则常见问题解答或联系opencode@microsoft.com，如有任何其他问题或建议。

附加文档

• Azure 门户
• 官方Azure监控文档
• OpenTelemetry Python官方文档