从适用于 Python 的 OpenCensus Python SDK 和 Azure Monitor OpenCensus 导出程序迁移到 Azure Monitor OpenTelemetry Python 发行版

项目
11/11/2024

注意

OpenCensus Python SDK 已弃用，但 Microsoft 会提供对它的支持，直至 2024 年 9 月 30 日停用它。我们现在推荐基于 OpenTelemetry 的 Python 产品/服务并提供迁移指南。

按照以下步骤将 Python 应用程序迁移到 Azure Monitor Application Insights OpenTelemetry 发行版。

警告

OpenCensus“如何迁移到 OpenTelemetry”博客不适用于 Azure Monitor 用户。
Microsoft 不建议或不支持OpenTelemetry OpenCensus 填充码。
下面概述了适用于 Azure Monitor 客户的唯一迁移计划。

步骤 1：卸载 OpenCensus 库

卸载与 OpenCensus 相关的所有库，包括以opencensus-*开头的所有 Pypi 包。

pip freeze | grep opencensus | xargs pip uninstall -y

步骤 2：从代码中删除 OpenCensus

从代码中删除 OpenCensus SDK 和 Azure Monitor OpenCensus 导出程序的所有实例。

检查以opencensus开头的导入语句，以查找必须删除的所有集成、导出者和 OpenCensus API/SDK 实例。

下面是必须删除的导入语句的示例。

from opencensus.ext.azure import metrics_exporter
from opencensus.stats import aggregation as aggregation_module
from opencensus.stats import measure as measure_module

from opencensus.ext.azure.trace_exporter import AzureExporter
from opencensus.trace.samplers import ProbabilitySampler
from opencensus.trace.tracer import Tracer

from opencensus.ext.azure.log_exporter import AzureLogHandler

步骤 3：熟悉 OpenTelemetry Python API/SDK

以下文档提供了 OpenTelemetry Python API/SDK 的先决条件知识。

OpenTelemetry Python 文档
有关配置和遥测的 Azure Monitor 发行版文档

注意

OpenTelemetry Python 和 OpenCensus Python 具有不同的 API 图面、自动收集功能和载入说明。

步骤 4：设置 Azure Monitor OpenTelemetry 发行版

按照入门页面载入 Azure Monitor OpenTelemetry 发行版。

更改和限制

从 OpenCensus 迁移到 OpenTelemetry 时，可能会遇到以下更改和限制。

Python < 3.7 支持

OpenTelemetry 的基于 Python 的监视解决方案仅支持 Python 3.7 及更高版本，但 OpenCensus 中之前受支持的 Python 版本 2.7、3.4、3.5 和 3.6 除外。建议为使用较旧版本的 Python 的用户进行升级，因为截至撰写本文档时，这些版本的生命周期已结束。坚持不升级的用户可能仍会使用 OpenTelemetry 解决方案，但可能会发现不受支持的意外或中断行为。在任何情况下，opencensus-ext-azure的最后受支持版本始终存在，对这些版本仍然有效，但不会为该项目发布新版本。

配置

OpenCensus Python 提供了一些与遥测收集和导出相关的配置选项。通过使用OpenTelemetry Python API 和 SDK，可以实现相同配置等目标。 OpenTelemetry Azure monitor Python 发行版更适合 Python 应用程序最常见的监视需求。由于发行版封装了 OpenTelemetry API/SDk，因此发行版目前可能不支持一些不常见用例的配置。相反，可以选择载入Azure monitor OpenTelemetry 导出程序，其与 OpenTelemetry API/SDK 结合使用应能够满足监视需求。其中一些配置包括：

自定义传播器
自定义采样器
添加额外的范围/日志处理器/指标读取器

Azure Functions 的内聚性

为了为在 Azure 函数中调用其他 Python 应用程序的 Python 应用程序提供分布式跟踪功能，提供了包opencensus-extension-azure-functions以允许连接的分布式图形。

目前，适用于 Azure Monitor 的 OpenTelemetry 解决方案不支持此方案。作为一种解决方法，可以在 Azure Functions 应用程序中手动传播跟踪上下文，如以下示例所示。

from opentelemetry.context import attach, detach
from opentelemetry.trace.propagation.tracecontext import \
  TraceContextTextMapPropagator

# Context parameter is provided for the body of the function
def main(req, context):
  functions_current_context = {
    "traceparent": context.trace_context.Traceparent,
    "tracestate": context.trace_context.Tracestate
  }
  parent_context = TraceContextTextMapPropagator().extract(
      carrier=functions_current_context
  )
  token = attach(parent_context)

  ...
  # Function logic
  ...
  detach(token)

扩展和导出程序

OpenCensus SDK 提供了通过 OpenCensus 集成和导出器分别收集和导出遥测的方法。在 OpenTelemetry 中，集成现在称为检测，而导出程序则保留相同的术语。 OpenTelemetry Python 检测和导出程序是 OpenCensus 中提供的超集，因此，就库覆盖范围和功能而言，OpenTelemetry 库是直接升级。至于 Azure Monitor OpenTelemetry 发行版，它附带一些现成的常用 OpenTelemetry Python 检测，因此无需额外代码。 Microsoft 完全支持这些检测。

对于此列表中未包含的其他 OpenTelemetry Python 检测，用户仍可能手动检测它们。但是，必须注意，在这些情况下无法保证或支持稳定性和行为。因此，请自行决定使用它们。

如果你想要建议将某个社区检测库加入我们的发行版，请在我们的反馈社区中发帖阐述想法或投票赞成。对于导出程序，Azure Monitor OpenTelemetry 发行版与Azure Monitor OpenTelemetry 导出程序捆绑在一起。如果还想使用其他导出程序，可以将其与发行版中结合使用，如以下示例所示。

TelemetryProcessors

OpenCensus Python 遥测处理器是一种功能强大的机制，允许用户在将遥测数据发送到导出程序之前对其进行修改。 OpenTelemetry 世界中没有 TelemetryProcessors 的概念，但可以使用 API 和类来复制相同的行为。

设置云角色名称和云角色实例

按照此处的说明操作，了解如何为遥测设置云角色名称和云角色实例。 OpenTelemetry Azure Monitor 发行版自动从环境变量中提取值并填充相应的字段。

使用 SpanProcessors 修改范围

即将推出。

使用视图修改指标