你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 Python 的 Azure Monitor Opentelemetry 发行版客户端库 - 版本 1.1.1

项目
12/06/2023

Opentelemetry Python 的 Azure Monitor 发行版提供了多个可用于 Opentelemetry Azure Monitor 监视解决方案的可安装组件。它允许检测 Python 应用程序，以便通过 Azure Monitor 导出程序捕获遥测数据并将其报告给 Azure Monitor。

此发行版会自动安装以下库：

Azure Monitor OpenTelemetry 导出程序
正式支持的 OpenTelemetry 检测的子集，如下所示。

官方支持的检测

OpenTelemetry 检测允许自动收集从基础检测库发送的请求。下面是与 Azure Monitor 发行版捆绑在一起的 OpenTelemetry 检测列表。默认情况下，这些检测处于启用状态。请参阅下面的 “使用情况 ”部分，了解如何选择退出这些检测。

检测	支持的库名称	支持的版本
Azure 核心跟踪 OpenTelemetry	`azure_sdk`
OpenTelemetry Django 检测	Django	链接
OpenTelemetry FastApi 检测	fastapi	链接
OpenTelemetry Flask 检测	flask	链接
OpenTelemetry Psycopg2 检测	psycopg2	链接
OpenTelemetry Requests Instrumentation	requests	链接
OpenTelemetry UrlLib 检测	urllib	全部
OpenTelemetry UrlLib3 检测	urllib3	链接

如果要添加对其他 OpenTelemetry 检测的支持，请提交功能请求。同时，可以通过自己的 API 手动使用 OpenTelemetry 检测， instrument() (即在代码中) 。请参阅此内容获取示例。

关键概念

此包捆绑了一系列 OpenTelemetry 和 Azure Monitor 组件，以便收集遥测数据并将其发送到 Azure Monitor。对于 MANUAL 检测，请使用 configure_azure_monitor 函数。尚不支持 AUTOMATIC 检测。

Azure Monitor OpenTelemetry 导出程序是实现此目的main组件。你将能够通过此包直接使用导出程序及其 API。请转到导出程序文档，了解 OpenTelemetry 和 Azure Monitor 组件在启用遥测收集和导出方面的工作原理。

目前，OpenTelemetry 中提供的所有检测都处于 beta 状态，这意味着它们不稳定，将来可能会有中断性变更。正在努力推动这些情况进入更稳定的状态。

入门

先决条件

若要使用此包，必须具有：

Azure 订阅 - 创建免费帐户
Azure Monitor - 如何使用 Application Insights
Opentelemetry SDK - 适用于 Python 的 Opentelemetry SDK
Python 3.7 或更高版本 - 安装 Python

安装包

使用 pip 安装 Azure Monitor Opentelemetry 发行版：

pip install azure-monitor-opentelemetry

使用情况

可以使用 configure_azure_monitor 为 Azure Monitor 的应用设置检测。 configure_azure_monitor 支持以下可选参数。所有传入参数都优先于任何相关的环境变量。

参数	说明	环境变量
`connection_string`	Application Insights 资源的连接字符串。如果未显式传入，将自动从`APPLICATIONINSIGHTS_CONNECTION_STRING`环境变量填充连接字符串。	`APPLICATIONINSIGHTS_CONNECTION_STRING`
`logger_name`	用于收集遥测数据的 Python 记录器的名称。	`N/A`
`instrumentation_options`	一个嵌套字典，用于确定要启用或禁用的检测。检测通过其库名称进行引用。例如， `{"azure_sdk": {"enabled": False}, "flask": {"enabled": False}, "django": {"enabled": True}}` 将禁用 Azure 核心跟踪和 Flask 检测，但保持 Django 和其他默认检测处于启用状态。 `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS`下面介绍的环境变量还可用于禁用检测。	`N/A`

可以使用 OpenTelemetry 环境变量进一步配置，例如： |环境变量 |说明 | |-------------|----------------------| | OTEL_SERVICE_NAME、 OTEL_RESOURCE_ATTRIBUTES |指定与应用程序关联的 OpenTelemetry 资源。 | | OTEL_LOGS_EXPORTER |如果设置为 None，则禁用日志记录遥测数据的收集和导出。 | | OTEL_METRICS_EXPORTER |如果设置为 None，则禁用指标遥测的收集和导出。 | | OTEL_TRACES_EXPORTER |如果设置为 None，则禁用分布式跟踪遥测数据的收集和导出。 | | OTEL_BLRP_SCHEDULE_DELAY |指定日志记录导出间隔（以毫秒为单位）。默认为 5000。 | | OTEL_BSP_SCHEDULE_DELAY |指定分布式跟踪导出间隔（以毫秒为单位）。默认为 5000。 | | OTEL_TRACES_SAMPLER_ARG |指定要采样的分布式跟踪遥测的比率。接受的值在 [0,1] 范围内。默认为 1.0，这意味着不会采样任何遥测数据。| | OTEL_PYTHON_DISABLED_INSTRUMENTATIONS |指定要禁用哪些受支持的检测。禁用的检测不会作为的 configure_azure_monitor一部分进行检测。但是，仍然可以直接手动检测 instrument() 它们。接受逗号分隔的小写库名称列表。例如，将设置为 "psycopg2,fastapi" 可禁用 Psycopg2 和 FastAPI 检测。默认为空列表，启用所有支持的检测。 | | OTEL_EXPERIMENTAL_RESOURCE_DETECTORS |实验性 OpenTelemetry 环境变量，用于指定要用于生成资源属性的资源检测器。这是一项实验性功能，此变量的名称及其行为可以以非向后兼容的方式更改。默认为“azure_app_service，azure_vm”，以便为Azure 应用服务和 Azure VM 启用 Azure 资源检测器。若要添加或删除特定的资源检测器，请相应地设置环境变量。有关详细信息，请参阅 OpenTelemetry Python 资源检测器文档。 |

Azure Monitor OpenTelemetry 导出程序配置

可以将 Azure monitor 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辅助角色本身发送日志记录遥测数据，而无需在调用 configure_azure_monitor()) (azure monitor sdk。这会导致在发送日志记录遥测时遇到重复的遥测条目。我们建议客户仅使用 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 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。直接按机器人提供的说明操作。只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与联系。

通过