從 OpenCensus Python SDK 和適用於 Python 的 Azure 監視器 OpenCensus 匯出工具移轉至 Azure 監視器 OpenTelemetry Python 發行版本

發行項
10/05/2024

注意

OpenCensus Python SDK 已淘汰，但 Microsoft 將持續提供支援，直到 2024 年 9 月 30 日淘汰為止。我們現在建議使用以 OpenTelemetry 為基礎的 Python 供應項目，並提供移轉指引。

請遵循下列步驟，將 Python 應用程式移轉至 Azure 監視器 Application Insights OpenTelemetry 發行版本。

警告

OpenCensus「如何移轉至 OpenTelemetry」部落格不適用於 Azure 監視器使用者。
Microsoft 不建議或支援 OpenTelemetry OpenCensus 填充碼。
下列概述 Azure 監視器客戶的唯一移轉方案。

步驟 1：解除安裝 OpenCensus 程式庫

解除安裝與 OpenCensus 相關的所有程式庫，包含 opencensus-* 開頭的所有 Pypi 套件。

pip freeze | grep opencensus | xargs pip uninstall -y

步驟 2：從程式碼移除 OpenCensus

從程式碼移除所有 OpenCensus SDK 和 Azure 監視器匯出工具的執行個體。

檢查檢查 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 APIs/SDK

下列文件提供 OpenTelemetry Python APIs/SDK 的必要條件知識。

OpenTelemetry Python 文件
設定和遙測的 Azure 監視器發行版本文件

注意

OpenTelemetry Python 和 OpenCensus Python 有不同的 API 介面、自動收集功能和上線指示。

步驟 4：設定 Azure 監視器 OpenTelemetry 發行版本

請遵循開始使用頁面以上線至 Azure 監視器 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 監視器 Python 發行版本是一站式服務，適用於 Python 應用程式最常見監視需求。由於發行版本封裝 OpenTelemetry API/SDK，因此發行版本目前可能不支援某些較不常見使用案例的設定。您可改為選擇上線至 Azure 監視器 OpenTelemetry 匯出工具，其中包含 OpenTelemetry API/SDK，應能夠符合監視需求。其中一些設定包含：

自訂傳播器
自訂取樣器
新增額外的跨度/記錄處理器/計量讀取器

內聚 Azure Functions

為了提供提供 Python 應用程式的分散式追蹤功能以在 Azure 函式中呼叫其他 Python 應用程式，已提供 opencensus-extension-azure-functions 套件以允許連線的分散式圖表。

目前 Azure 監視器的 OpenTelemetry 解決方案目前不支援此案例。作為因應措施，您可手動在 Azure 函式應用程式中傳播追蹤內容，如下列範例所示。

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 監視器 OpenTelemetry 發行版本，其中隨附一熱門現成可用的 OpenTelemetry Python 檢測，不需要額外的程式碼。 Microsoft 完全支援這些檢測設備。

針對其他此清單中未包含的 OpenTelemetry Python 檢測設備，使用者仍可手動使用這些檢測進行檢測。然而，請務必注意，在這些情況下，無法保證或支援穩定性和行為。因此，請自行判斷是否要使用。

如果您想要向我們建議社群檢測程式庫以包含在發行版本，請在意見反應社群中張貼或贊同想法。針對輸出工具，Azure 監視器 OpenTelemetry 發行版本隨附於 Azure 監視器 OpenTelemetry 匯出工具。如果您也想要使用其他匯出工具，您可以與發行版本一起使用，如此範例。

TelemetryProcessors

OpenCensus Python 遙測處理器是強大的機制，可讓使用者在傳送至匯出工具前修改其遙測。 OpenTelemetry 沒有 TelemetryProcessors 的概念，但您可使用 API 和類別來複寫相同的行為。

設定雲端角色名稱和雲端角色執行個體

請遵循這裡的指示，了解如何設定遙測的雲端角色名稱和雲端角色執行個體。 OpenTelemetry Azure 監視器發行版本會自動從環境變數擷取值並填入個別欄位。

使用 SpanProcessors 修改跨度

即將推出。

使用 Views 修改計量