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

注意

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

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

警告

• 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 函式

為了提供提供 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 修改計量

即將推出。

效能計數器

OpenCensus Python Azure 監視器匯出工具會自動收集系統與效能相關的計量，稱為效能計數器。 這些計量會顯示在 Application Insights 執行個體的 performanceCounters 中。 在 OpenTelemetry 中，我們不再明確將這些計量傳送至 performanceCounters。 與傳入/傳出要求相關的計量可在標準計量下找到。 如果您要 OpenTelemetry 自動收集系統相關計量，您可使用 OpenTelemetry Python 社群參與的實驗系統計量檢測。 此套件是實驗性質，Microsoft 並未正式支援。

疑難排解

ASP.NET Core

步驟 1：啟用診斷記錄

Azure 監視器匯出工具使用 EventSource 進行其內部記錄。 透過選擇名稱為 OpenTelemetry-AzureMonitor-Exporter 的來源，任何 EventListener 都可以使用匯出工具記錄。 如需疑難排解步驟，請參閱 GitHub 上的 OpenTelemetry 疑難排解。

步驟 2：測試應用程式主機與內嵌服務之間的連線

Application Insights SDK 和代理程式會傳送遙測，以內嵌為 REST 呼叫內嵌到我們內嵌的端點。 若要測試從 Web 伺服器或應用程式主機電腦到內嵌服務端點的連線，請使用來自 PowerShell 的 curl 命令或原始 REST 要求。 如需詳細資訊，請參閱針對 Azure 監視器 Application Insights 中遺失的應用程式遙測進行疑難排解。

已知問題

下列項目是 Azure 監視器 OpenTelemetry 匯出工具的已知問題：

• 相依性遙測資料中缺少操作名稱。 缺少操作名稱會導致失敗，並對性能索引標籤體驗產生負面影響。

• 要求和相依性遙測資料中缺少裝置型號。 缺少裝置型號會對裝置世代分析產生不利影響。

.NET

步驟 1：啟用診斷記錄

Azure 監視器匯出工具使用 EventSource 進行其內部記錄。 透過選擇名稱為 OpenTelemetry-AzureMonitor-Exporter 的來源，任何 EventListener 都可以使用匯出工具記錄。 如需疑難排解步驟，請參閱 GitHub 上的 OpenTelemetry 疑難排解。

步驟 2：測試應用程式主機與內嵌服務之間的連線

Application Insights SDK 和代理程式會傳送遙測，以內嵌為 REST 呼叫內嵌到我們內嵌的端點。 若要測試從 Web 伺服器或應用程式主機電腦到內嵌服務端點的連線，請使用來自 PowerShell 的 curl 命令或原始 REST 要求。 如需詳細資訊，請參閱針對 Azure 監視器 Application Insights 中遺失的應用程式遙測進行疑難排解。

已知問題

下列項目是 Azure 監視器 OpenTelemetry 匯出工具的已知問題：

• 相依性遙測資料中缺少操作名稱。 缺少操作名稱會導致失敗，並對性能索引標籤體驗產生負面影響。

• 要求和相依性遙測資料中缺少裝置型號。 缺少裝置型號會對裝置世代分析產生不利影響。

Java

步驟 1：啟用診斷記錄

根據預設，Azure Monitor Application Insights 中啟用診斷記錄。 如需詳細資訊，請參閱疑難排解指南：適用於 JAVA 的 Azure 監視器 Application Insights。

步驟 2：測試應用程式主機與內嵌服務之間的連線

Application Insights SDK 和代理程式會傳送遙測，以內嵌為 REST 呼叫內嵌到我們內嵌的端點。 若要測試從 Web 伺服器或應用程式主機電腦到內嵌服務端點的連線，請使用來自 PowerShell 的 curl 命令或原始 REST 要求。 如需詳細資訊，請參閱針對 Azure 監視器 Application Insights 中遺失的應用程式遙測進行疑難排解。

已知問題

• 如果從瀏覽器下載 Application Insights 用戶端程式庫進行安裝，有時下載的 JAR 檔案已損毀，大小約為來源檔案的一半。 如果遇到此問題，請透過執行 curl 或 wget 命令下載 JAR 檔案，如下列範例命令呼叫所示：

  curl --location --output applicationinsights-agent-3.4.11.jar https://github.com/microsoft/ApplicationInsights-Java/releases/download/3.4.11/applicationinsights-agent-3.4.11.jar
  

  wget --output-document=applicationinsights-agent-3.4.11.jar https://github.com/microsoft/ApplicationInsights-Java/releases/download/3.4.11/applicationinsights-agent-3.4.11.jar
  

  注意

  範例命令呼叫適用於 Application Insights for Java 版本 3.4.11。 若要尋找目前版本的 Application Insights for Java 的版本編號和 URL 位址，請參閱 https://github.com/microsoft/ApplicationInsights-Java/releases。

JAVA 原生

下列步驟適用於 Spring Boot 原生應用程式。

步驟 1：驗證 OpenTelemetry 版本

應用程式啟動過程中，您可能會注意到以下訊息：

WARN  c.a.m.a.s.OpenTelemetryVersionCheckRunner - The OpenTelemetry version is not compatible with the spring-cloud-azure-starter-monitor dependency.
The OpenTelemetry version should be <version>

在這種情況下，您必須按照 Spring Boot starter 中的 OpenTelemetry 文件匯入 OpenTelemetry 用料表。

步驟 2：啟用自我診斷

如果未按預期工作，則可以在 DEBUG 等級啟用自我診斷以取得深入解析。 若要這樣做，請使用 APPLICATIONINSIGHTS_SELF_DIAGNOSTICS_LEVEL 環境變數，將自我診斷等級設定為 ERROR、WARN、INFO、DEBUG 或 TRACE。

若要在執行 Docker 容器時在 DEBUG 等級啟用自我診斷，請執行下列命令：

docker run -e APPLICATIONINSIGHTS_SELF_DIAGNOSTICS_LEVEL=DEBUG <image-name>

注意

對應使用 Docker 映像名稱取代 <image-name>。

協力廠商資訊免責聲明

本文提及的協力廠商產品是由與 Microsoft 無關的獨立廠商所製造。 Microsoft 不以默示或其他方式，提供與這些產品的效能或可靠性有關的擔保。

Node.js

步驟 1：啟用診斷記錄

Azure 監視器匯出工具使用 OpenTelemetry API 記錄器進行內部記錄。 若要啟用記錄器，請執行下列程式碼片段：

const { diag, DiagConsoleLogger, DiagLogLevel } = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");

const provider = new NodeTracerProvider();
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ALL);
provider.register();

步驟 2：測試應用程式主機與內嵌服務之間的連線

Application Insights SDK 和代理程式會傳送遙測，以內嵌為 REST 呼叫內嵌到我們內嵌的端點。 若要測試從 Web 伺服器或應用程式主機電腦到內嵌服務端點的連線，請使用來自 PowerShell 的 curl 命令或原始 REST 要求。 如需詳細資訊，請參閱針對 Azure 監視器 Application Insights 中遺失的應用程式遙測進行疑難排解。

已知問題

下列項目是 Azure 監視器 OpenTelemetry 匯出工具的已知問題：

• 相依性遙測資料中缺少操作名稱。 缺少操作名稱會導致失敗，並對性能索引標籤體驗產生負面影響。

• 要求和相依性遙測資料中缺少裝置型號。 缺少裝置型號會對裝置世代分析產生不利影響。

• 相依性名稱缺少資料庫伺服器名稱。 由於不包括資料庫伺服器名稱，因此 OpenTelemetry 匯出程式會錯誤地將具有相同名稱的資料表彙總到不同的伺服器上。

Python

步驟 1：啟用診斷記錄

Microsoft Azure 監視器匯出工具使用 Python 標準記錄程式庫進行其內部記錄。 對於異常活動，OpenTelemetry API 和 Azure 監視器匯出工具記錄會以 WARNING 或 ERROR 嚴重性層級來加以記錄。 INFO 嚴重性層級用來表示一般或成功的活動。

根據預設，Python 記錄程式庫將嚴重性等級設定為 WARNING。 因此，您必須變更嚴重性等級，才能在此嚴重性設定下查看記錄。 下列範例示範程式碼如何將所有嚴重性層級的記錄輸出到主控台和檔案：

...
import logging

logging.basicConfig(format = "%(asctime)s:%(levelname)s:%(message)s", level = logging.DEBUG)

logger = logging.getLogger(__name__)
file = logging.FileHandler("example.log")
stream = logging.StreamHandler()
logger.addHandler(file)
logger.addHandler(stream)
...

步驟 2：測試應用程式主機與內嵌服務之間的連線

Application Insights SDK 和代理程式會傳送遙測，以內嵌為 REST 呼叫內嵌到我們內嵌的端點。 若要測試從 Web 伺服器或應用程式主機電腦到內嵌服務端點的連線，請使用來自 PowerShell 的 curl 命令或原始 REST 要求。 如需詳細資訊，請參閱針對 Azure 監視器 Application Insights 中遺失的應用程式遙測進行疑難排解。

步驟 3：避免重複遙測

如果您建立多個處理器或匯出工具的執行個體，通常會造成重複遙測。 請確定您一次只針對遙測要素執行一個匯出工具和處理器 (記錄、計量和分散式追蹤)。

下列各節說明可能導致重複遙測的案例。

Azure Functions 中的重複追蹤記錄

如果您在 Application Insights 內看到每個追蹤記錄的一對項目，您可能已啟用下列類型的記錄檢測：

• Azure Functions 中的原生記錄檢測
• 發行版本內的 azure-monitor-opentelemetry 記錄檢測

若要避免重複，您可以停用發行版本的記錄，但讓 Azure Functions 中的原生記錄檢測保持啟用。 若要這麼做，請將 OTEL_LOGS_EXPORTER 環境變數設定為 None。

Azure Functions 中「一律開啟」的重複遙測

如果 Azure Functions 中的 [一律開啟] 設定設為開啟，Azure Functions 會在每次執行完成後，讓某些程序在背景中執行。 例如，假設您有一個每五分鐘呼叫 configure_azure_monitor 的函數。 20 分鐘之後，您可能會有四個計量匯出工具同時執行。 這種情況可能是重複計量遙測的來源。

在此情況下，請將 [一律開啟] 設定為 [關閉]，或嘗試手動關閉每個 configure_azure_monitor 呼叫之間的提供者。 若要關閉每個提供者，請針對每個目前的計量、追蹤器和記錄器提供者執行關機呼叫，如下列程式碼所示：

get_meter_provider().shutdown()
get_tracer_provider().shutdown()
get_logger_provider().shutdown()

Azure Workbooks 和 Jupyter Notebooks

Azure Workbooks 和 Jupyter Notebook 可能會讓匯出工具在背景中執行。 若要防止重複遙測，請先清除快取，再呼叫 configure_azure_monitor。

步驟 4：確定已收集 Flask 要求資料

如果您實作 Flask 應用程式，您可能會發現在使用適用於 Python 的 Azure 監視器 OpenTelemetry Distro 用戶端程式庫時，無法從 Application Insights 收集要求資料表資料。 如果您未正確建構 import 宣告，就可能發生此問題。 在呼叫 configure_azure_monitor 函式以檢測 Flask 程式庫之前，您可能先匯入 flask.Flask Web 應用程式架構。 例如，下列程式碼無法成功檢測 Flask 應用程式：

from azure.monitor.opentelemetry import configure_azure_monitor
from flask import Flask

configure_azure_monitor()

app = Flask(__name__)

相反，建議您匯入整個 flask 模組，然後呼叫 configure_azure_monitor 來設定 OpenTelemetry 以在存取 flask.Flask 之前使用 Azure 監視器：

from azure.monitor.opentelemetry import configure_azure_monitor
import flask

configure_azure_monitor()

app = flask.Flask(__name__)

或者，您可以在匯入 flask.Flask 之前呼叫 configure_azure_monitor：

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor()

from flask import Flask

app = Flask(__name__)

支援

選取您選擇的語言索引標籤，以探索支援選項。

ASP.NET Core

• 針對 Azure 支援問題，請開啟 Azure 支援票證。
• 針對 OpenTelemetry 問題，請直接連絡 OpenTelemetry .NET 社群。
• 如需與 Azure 監視器匯出工具相關的未解決問題清單，請參閱 GitHub 問題頁面。

.NET

• 針對 Azure 支援問題，請開啟 Azure 支援票證。
• 針對 OpenTelemetry 問題，請直接連絡 OpenTelemetry .NET 社群。
• 如需與 Azure 監視器匯出工具相關的未解決問題清單，請參閱 GitHub 問題頁面。

Java

• 針對 Azure 支援問題，請開啟 Azure 支援票證。
• 如需疑難排解的協助，請檢閱疑難排解步驟。
• 針對 OpenTelemetry 問題，請直接連絡 OpenTelemetry 社群。
• 如需與 Azure 監視器 Java 自動檢測相關的未解決問題清單，請參閱 GitHub 問題頁面。

JAVA 原生

• 針對 Azure 支援問題，請開啟 Azure 支援票證。
• 針對 OpenTelemetry 問題，請直接連絡 OpenTelemetry 社群。
• 有關 Spring Boot 原生應用程式的未解決問題清單，請參閱 GitHub 問題頁面。
• 有關 Quarkus 原生應用程式的未解決問題清單，請參閱 GitHub 問題頁面。

Node.js

• 針對 Azure 支援問題，請開啟 Azure 支援票證。
• 針對 OpenTelemetry 問題，請直接連絡 OpenTelemetry JavaScript 社群。
• 如需與 Azure 監視器匯出工具相關的未解決問題清單，請參閱 GitHub 問題頁面。

Python

• 針對 Azure 支援問題，請開啟 Azure 支援票證。
• 針對 OpenTelemetry 問題，請直接連絡 OpenTelemetry Python 社群。
• 如需與 Azure 監視器發行版本相關的未解決問題清單，請參閱 GitHub 問題頁面。

OpenTelemetry 意見反應

若要提供意見反應：

• 填寫 OpenTelemetry 社群的客戶意見反應問卷。
• 加入 OpenTelemetry 早期採用者社群，告知 Microsoft 有關您自己的資訊。
• 與 Microsoft Tech Community 中的其他 Azure 監視器使用者互動。
• 在 Azure 意見反應論壇中提出功能要求。