Python 用 Azure Monitor Opentelemetry Distro クライアント ライブラリ - バージョン 1.1.1

Opentelemetry Python の Azure Monitor ディストリビューションには、Opentelemetry Azure Monitor 監視ソリューションで使用できる複数のインストール可能なコンポーネントが用意されています。 これにより、Python アプリケーションをインストルメント化して、Azure Monitor エクスポーターを介してテレメトリをキャプチャして Azure Monitor に報告することができます。

このディストリビューションでは、次のライブラリが自動的にインストールされます。

• Azure Monitor OpenTelemetry エクスポーター
• 以下に示すように正式にサポートされている OpenTelemetry インストルメンテーション のサブセット。

公式にサポートされているインストルメンテーション

OpenTelemetry インストルメンテーションを使用すると、基になるインストルメント化されたライブラリから送信された要求を自動的に収集できます。 Azure monitor ディストリビューションにバンドルされている OpenTelemetry インストルメンテーションの一覧を次に示します。 これらのインストルメンテーションは、既定で有効になっています。 これらのインストルメンテーションをオプトアウトする方法については、以下の 「使用法 」セクションを参照してください。

別の OpenTelemetry インストルメンテーションのサポートを追加する場合は、機能 要求を送信してください。 それまでの間は、コード内の独自の API (つまり instrument()) を使用して、OpenTelemetry インストルメンテーションを手動で使用できます。 例については、こちらをご覧ください。

主要な概念

このパッケージは、一連の OpenTelemetry コンポーネントと Azure Monitor コンポーネントをバンドルして、Azure Monitor へのテレメトリの収集と送信を可能にします。 MANUAL インストルメンテーションの場合は、 関数を使用します configure_azure_monitor 。 AUTOMATIC インストルメンテーションはまだサポートされていません。

Azure Monitor OpenTelemetry エクスポーターは、これを実現するためのメインコンポーネントです。 エクスポーターとその API は、このパッケージを通じて直接使用できます。 テレメトリの収集とエクスポートを有効にする場合に OpenTelemetry コンポーネントと Azure Monitor コンポーネントがどのように機能するかについては、エクスポーターのドキュメントを参照してください。

現在、OpenTelemetry で使用できるすべてのインストルメンテーションはベータ状態です。つまり、安定していないため、将来重大な変更が発生する可能性があります。 これらをより安定した状態に押し上げる取り組みが行われています。

作業の開始

前提条件

このパッケージを使用するには、次が必要です。

• Azure サブスクリプション - 無料アカウントを作成できます
• Azure Monitor - Application Insights を使用する方法
• Opentelemetry SDK - Opentelemetry SDK for Python
• Python 3.7 以降 - Python をインストールする

パッケージをインストールする

pip を使用して Azure Monitor Opentelemetry Distro をインストールします。

pip install azure-monitor-opentelemetry

使用

を使用 configure_azure_monitor して、アプリのインストルメンテーションを Azure Monitor に設定できます。 configure_azure_monitor では、次の省略可能な引数がサポートされています。 すべてのパススルー パラメーターは、関連する環境変数よりも優先されます。

次のような OpenTelemetry 環境変数を使用してさらに構成できます。 |環境変数 |説明 | |-------------|----------------------| |OTEL_SERVICE_NAME、OTEL_RESOURCE_ATTRIBUTES |アプリケーションに関連付けられている OpenTelemetry リソースを指定します。 | | OTEL_LOGS_EXPORTER |に設定すると None、ログ テレメトリの収集とエクスポートが無効になります。 | | OTEL_METRICS_EXPORTER |に設定すると None、メトリック テレメトリの収集とエクスポートが無効になります。 | | OTEL_TRACES_EXPORTER |に設定すると None、分散トレース テレメトリの収集とエクスポートが無効になります。 | | OTEL_BLRP_SCHEDULE_DELAY |ログのエクスポート間隔をミリ秒単位で指定します。 既定値は 5000 です。 | | OTEL_BSP_SCHEDULE_DELAY |分散トレース エクスポート間隔をミリ秒単位で指定します。 既定値は 5000 です。 | | OTEL_TRACES_SAMPLER_ARG | サンプリングする分散トレース テレメトリの比率を指定します。 指定できる値の範囲は [0,1] です。 既定値は 1.0 です。つまり、テレメトリはサンプリングされません。| | OTEL_PYTHON_DISABLED_INSTRUMENTATIONS |サポートされているインストルメンテーションのうち、無効にするインストルメンテーションを指定します。 無効なインストルメンテーションは の一部 configure_azure_monitorとしてインストルメント化されません。 ただし、手動で instrument() 直接インストルメント化することはできます。 小文字の ライブラリ名のコンマ区切りのリストを受け入れます。 たとえば、 を に "psycopg2,fastapi" 設定して、Psycopg2 および FastAPI インストルメンテーションを無効にします。 既定では空のリストが使用され、サポートされているすべてのインストルメンテーションが有効になります。 | | OTEL_EXPERIMENTAL_RESOURCE_DETECTORS |リソース属性の生成に使用する Resource Detector を指定するために使用される試験的な OpenTelemetry 環境変数。 これは実験的な機能であり、この変数の名前とその動作は、下位互換性のない方法で変更される可能性があります。 Azure App Serviceと Azure VM に対して Azure Resource Detectors を有効にするには、既定値は "azure_app_service,azure_vm" です。 特定のリソース検出機能を追加または削除するには、それに応じて環境変数を設定します。 詳細については、 OpenTelemetry Python Resource Detector のドキュメントを参照してください 。 |

Azure Monitor OpenTelemetry Exporter の構成

Azure Monitor OpenTelemetry エクスポーター構成パラメーターを に直接 configure_azure_monitor渡すことができます。 エクスポートに関連する追加の構成については、こちらを参照してください。

...
configure_azure_monitor(
   connection_string="<your-connection-string>",
   disable_offline_storage=True,
)
...

例

上記の構成オプションを利用する方法を示すサンプル については、こちらを参照してください 。

Azure Functionsでの監視

トレースの相関付け

Azure Functionsでホストされている Python アプリケーションに送信される追跡された受信要求は、その中で追跡されているテレメトリと自動的に関連付けされません。 トレースの関連付けを手動で実現するには、次に示すように を TraceContext 直接抽出します。

import azure.functions as func

from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace
from opentelemetry.propagate import extract

# Configure Azure monitor collection telemetry pipeline
configure_azure_monitor()

def main(req: func.HttpRequest, context) -> func.HttpResponse:
   ...
   # Store current TraceContext in dictionary format
   carrier = {
      "traceparent": context.trace_context.Traceparent,
      "tracestate": context.trace_context.Tracestate,
   }
   tracer = trace.get_tracer(__name__)
   # Start a span using the current context
   with tracer.start_as_current_span(
      "http_trigger_span",
      context=extract(carrier),
   ):
      ...

ログの問題

Azure Functions worker 自体は、azure monitor sdk (への呼び出し) を使用せずに、ログ テレメトリ自体をconfigure_azure_monitor()送信します。 これにより、ログ テレメトリを送信するときに、テレメトリ エントリの重複が発生する可能性があります。 お客様に対する推奨事項は、SDK のみを使用することです。これにより、Azure Functions worker によって提供される組み込み製品を使用するよりもはるかに豊富なテレメトリと機能が可能になります。 ロガーのハンドラーの一覧をクリアすることで、Azure Functionsテレメトリ ロガーをオフにすることができます。

...
root_logger = logging.getLogger()
for handler in root_logger.handlers[:]:
    root_logger.removeHandler(handler)
...

ロガーまたは の呼び出しがセットアップされる前に、必ず上記を呼び出 configure_azure_monitor() してください。

Azure Functions構成を使用してログ記録を無効にすることもできます。

v2.x+

...
{
  "logging": {
    ...
    "logLevel": {
      "default": "None",
      ...
    }
  }
}
...

v1.x

...
{
  "logger": {
    "categoryFilter": {
      "defaultLevel": "None",
      ...
    }
  }
}
...

トラブルシューティング

エクスポーターは 、Azure Core で定義されている例外を発生させます。

次の手順

詳細については、 ドキュメント を参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

その他のドキュメント

• Azure Portal
• Azure Monitor の公式ドキュメント
• OpenTelemetry Python 公式ドキュメント