OpenCensus Python SDK と Python 用の Azure Monitor OpenCensus エクスポーターから Azure Monitor OpenTelemetry Python Distro に移行する

[アーティクル]
10/10/2023

Note

OpenCensus Python SDK は非推奨ですが、Microsoft は 2024 年 9 月 30 日に廃止されるまでサポートします。現在は OpenTelemetry ベースの Python オファリングを推奨しており、移行ガイダンスを提供しています。

Python アプリケーションを Azure Monitor Application Insights OpenTelemetry Distro に移行するには、以下の手順に従います。

警告

OpenCensus の OpenTelemetry への移行方法に関するブログは、Azure Monitor ユーザーには当てはまりません。
OpenTelemetry OpenCensus shim は、Microsoft で推奨もサポートもされていません。
以下の概要には、Azure Monitor のお客様向けの移行プランのみが示されています。

手順 1: OpenCensus ライブラリをアンインストールする

opencensus-* で始まるすべての Pypi パッケージを含め、OpenCensus に関連するすべてのライブラリをアンインストールします。

pip freeze | grep opencensus | xargs pip uninstall -y

手順 2: コードから OpenCensus を削除する

コードから、OpenCensus SDK と Azure Monitor OpenCensus エクスポーターのすべてのインスタンスを削除します。

opencensus で始まる import ステートメントを確認して、削除する必要がある OpenCensus API/SDK のすべての統合、エクスポーター、インスタンスを見つけてください。

削除する必要がある import ステートメントの例を次に示します。

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 Distro のドキュメント

注意

OpenTelemetry Python と OpenCensus Python とでは、API サーフェス、自動収集機能、オンボード手順が異なります。

手順 4: Azure Monitor OpenTelemetry Distro を設定する

「作業の開始」ページに従って、Azure Monitor OpenTelemetry Distro にオンボードします。

変更点と制限

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 Distro は、Python アプリケーションの最も一般的な監視ニーズに応えるワンストップショップ以上のものです。このディストリビューションでは OpenTelemetry API/SDK がカプセル化されているため、あまり一般的ではないユースケースでは一部の構成がこのディストリビューションで現在サポートされていない可能性があります。代わりに、OpenTelemetry API/SDK と共に特定の監視ニーズを満たすことができる Azure Monitor OpenTelemetry エクスポーターへのオンボードを選択することができます。そのような構成の一部を次に示します。

カスタムプロパゲーター
カスタムサンプラー
追加のスパン/ログプロセッサ/メトリックリーダーの追加

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 Distro については、すぐに使用できるいくつかの一般的な OpenTelemetry Python インストルメンテーションを備えているため、追加のコードは不要です。 Microsoft は、それらのインストルメンテーションを完全にサポートしています。

この一覧に含まれない他の OpenTelemetry Python インストルメンテーションについても、ユーザーはそれらを手動で備えることができます。ただし、そのような場合、安定性と動作は保証もサポートもされないことに注意することが重要です。そのため、ご自身の判断で使用してください。

コミュニティインストルメンテーションライブラリを提案する場合は、フィードバックコミュニティにアイデアを投稿またはアップ投票します。エクスポーターについては、Azure Monitor OpenTelemetry Distro に Azure Monitor OpenTelemetry エクスポーターがバンドルされています。他のエクスポーターも使用する場合は、この例のように、それらをディストリビューションと共に使用できます。

TelemetryProcessors

OpenCensus Python テレメトリプロセッサは、ユーザーがテレメトリをエクスポーターへの送信前に変更できるようにする強力なメカニズムです。 OpenTelemetry の世界にはテレメトリプロセッサの概念はありませんが、同じ動作を再現するために使用できる API とクラスが用意されています。

クラウドロール名とクラウドロールインスタンスを設定する

テレメトリのためにクラウドロール名とクラウドロールインスタンスを設定する方法については、こちらの手順に従ってください。 OpenTelemetry Azure Monitor Distro は、自動的に環境変数から値をフェッチし、それぞれのフィールドを設定します。

SpanProcessor を使用してスパンを変更する

近日対応予定。

ビューを使用してメトリックを変更する

近日対応予定。

パフォーマンスカウンター

OpenCensus Python Azure Monitor エクスポーターは、パフォーマンスカウンターと呼ばれる、システムおよびパフォーマンス関連のメトリックを自動的に収集していました。これらのメトリックは、Application Insights の performanceCounters に表示されます。 OpenTelemetry では、これらのメトリックが performanceCounters に明示的に送信されなくなります。受信/送信要求に関連するメトリックは、標準メトリックで確認できます。 OpenTelemetry でシステム関連のメトリックを自動収集する場合は、OpenTelemetry Python コミュニティによって提供されている、試験段階のシステムメトリックインストルメンテーションを使用することができます。このパッケージは試験段階のものであり、Microsoft によって正式にサポートされていません。

トラブルシューティング

動作していませんか? ASP.NET Core のトラブルシューティングページをご確認ください。

サポート

選択した言語のタブを選択して、サポートオプションを検出します。

Azure サポートの問題については、Azure サポートチケットを開いてください。
OpenTelemetry の問題については、OpenTelemetry .NET コミュニティに直接問い合わせてください。
Azure Monitor Exporter に関連する未解決の問題の一覧については、GitHub のイシューページを参照してください。

OpenTelemetry のフィードバック

フィードバックを提供するには:

OpenTelemetry コミュニティのカスタマーフィードバックアンケートに記入してください。
Microsoft の OpenTelemetry 早期導入者コミュニティに参加して、お客様自身のことをお知らせください。
Microsoft Tech Community で他の Azure Monitor ユーザーと交流してください。
Azure フィードバックフォーラムで機能に関する要求を行ってください。