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

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 によって正式にサポートされていません。

サポート

トラブルシューティング手順、サポート オプションを確認する場合、または OpenTelemetry のフィードバックを提供する場合は、「Azure Monitor Application Insights の OpenTelemetry に関するトラブルシューティング、サポート、フィードバック」を参照してください。