Azure Core Tracing OpenTelemetry客户端库（Python版）

入门指南

安装包

使用 pip 安装Azure Core OpenTelemetry Tracing插件（Python版）

pip install azure-core-tracing-opentelemetry

现在您可以使用与azure-core tracing兼容的任何SDK使用Python OpenTelemetry，这包括（不一一列举），azure-storage-blob，azure-keyvault-secrets，azure-eventhub等。

关键概念

• 您不需要传递任何上下文，SDK将为您获取它

• 有两种方法在代码中启用跟踪插件

  from azure.core.settings import settings
  from azure.core.tracing.ext.opentelemetry_span import OpenTelemetrySpan
  settings.tracing_implementation = OpenTelemetrySpan
  

  或

  from azure.core.settings import settings
  settings.tracing_implementation = "opentelemetry"
  

• 或者，如果您已安装最新版本的 azure-core，您也可以设置以下环境变量以使用OpenTelemetry启用跟踪

  AZURE_SDK_TRACING_IMPLEMENTATION=opentelemetry
  

示例

没有明确的上下文需要传递，您只需创建您通常的OpenTelemetry跟踪器并调用任何与azure-core跟踪兼容的SDK代码。以下是一个使用Azure Monitor导出器的示例，但您可以使用任何导出器（Zipkin等）。

# Declare OpenTelemetry as enabled tracing plugin for Azure SDKs
from azure.core.settings import settings

settings.tracing_implementation = "opentelemetry"

# In the below example, we use a simple console exporter, uncomment these lines to use
# the OpenTelemetry exporter for Azure Monitor.
# Example of a trace exporter for Azure Monitor, but you can use anything OpenTelemetry supports
# from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
# exporter = AzureMonitorTraceExporter(
#     connection_string="the connection string used for your Application Insights resource"
# )

# Regular open telemetry usage from here, see https://github.com/open-telemetry/opentelemetry-python
# for details
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter
from opentelemetry.sdk.trace.export import SimpleSpanProcessor

# Simple console exporter
exporter = ConsoleSpanExporter()

trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)
trace.get_tracer_provider().add_span_processor(
    SimpleSpanProcessor(exporter)
)

# Example with Storage SDKs

from azure.storage.blob import BlobServiceClient

with tracer.start_as_current_span(name="MyApplication"):
    client = BlobServiceClient.from_connection_string('connectionstring')
    client.create_container('my_container')  # Call will be traced

Azure Monitor OpenTelemetry导出器可以在azure-monitor-opentelemetry-exporter包中找到。

HTTP 仪器

启用Azure Core OpenTelemetry跟踪插件后，Azure SDK客户端发出的HTTP请求通常会通过DistributedTracingPolicy自动进行仪器化。由于Azure Core处理Azure服务调用的HTTP仪器化，因此会抑制来自其他库（如opentelemetry-requests-instrumentation）的自动HTTP仪器化，以避免创建重复的跨度。

故障排除

此客户端会引发Azure Core中定义的异常。

下一步

有关OpenTelemetry配置的更多文档可以在OpenTelemetry网站上找到。

贡献

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

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

本项目采用了Microsoft开源代码行为准则。有关更多信息，请参阅代码行为准则FAQ或联系opencode@microsoft.com，如有任何其他问题或评论。

发行历史

1.0.0b11（2023-09-07）

修复的bug

• 修复了将OpenTelemetrySpan类型正确实现为AbstractSpan协议。(#31943)

1.0.0b10（2023-07-11）

添加的功能

• 启用了使用context关键字参数传递父跨度上下文头部的功能。这将是创建跨度时使用的父上下文。(#30411)

破坏性更改

• 将某些属性重新映射，以与OpenTelemetry语义约定一致（#29203）
  • x-ms-client-request-id -> az.client_request_id,
  • x-ms-request-id -> az.service_request_id,
  • http.user_agent -> user_agent.original,
  • message_bus.destination -> messaging.destination.name,
  • peer.address -> net.peer.name,

其他更改

• Python 2.7不再受支持。请使用Python 3.7或更高版本。
• 嵌套内部跨度现在仅抑制最外层的内部跨度，记录最外层的内部跨度。嵌套客户端跨度将是外部跨度子代。(#29616)
• 创建客户端跨度时，会设置一个标志，指示应抑制自动HTTP仪器化。由于azure-core已经进行了HTTP调用仪器化，这可以防止产生重复的跨度。(#29616)
• 现在在跟踪器的仪器作用域上设置了模式URL。(#30014)
• 最低opentelemetry-api依赖项提升到1.12.0。
• 最低azure-core依赖项提升到1.24.0。

1.0.0b9（2021-04-06）

• 更新opentelemetry-api到版本1.0.0
• 现在可以在创建跨度实例时添加Link和SpanKind。

1.0.0b8（2021-02-08）

• 将opentelemetry-api固定在版本0.17b0

1.0.0b7（2020-10-05）

• 将opentelemetry-api固定在版本0.13b0

1.0.0b6（2020-07-06）

• 将 opentelemetry-api 锁定到版本 0.10b0

1.0.0b5 (2020-06-08)

• 将 opentelemetry-api 锁定到版本 0.8b0
• 修复了一个问题，其中 DefaultSpan 有时抛出 AttributeError。

1.0.0b4 (2020-05-04)

• link 和 link_from_headers 现在接受属性。

1.0.0b3 (2020-04-06)

功能

• 将 opentelemetry-api 锁定到版本 0.6b0

1.0.0b2 (2020-03-09)

功能

• 将 opentelemetry-api 锁定到版本 0.4a0

1.0.0b1

功能

• OpenTelemetry 的 azure-core 追踪协议实现