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

[アーティクル]
12/06/2023

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

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

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

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

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

インストルメンテーション	サポートされているライブラリ名	サポートされているバージョン
Azure Core Tracing OpenTelemetry	`azure_sdk`
OpenTelemetry Django Instrumentation	Django	(リンク)
OpenTelemetry FastApi Instrumentation	fastapi	(リンク)
OpenTelemetry Flask Instrumentation	flask	(リンク)
OpenTelemetry Psycopg2 Instrumentation	psycopg2	(リンク)
OpenTelemetry Requests Instrumentation	requests	(リンク)
OpenTelemetry UrlLib インストルメンテーション	urllib	すべて
OpenTelemetry UrlLib3 Instrumentation	urllib3	(リンク)

別の 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 では、次の省略可能な引数がサポートされています。すべてのパススルーパラメーターは、関連する環境変数よりも優先されます。

パラメーター	説明	環境変数
`connection_string`	Application Insights リソースの接続文字列。明示的に渡されない場合、接続文字列は環境変数から`APPLICATIONINSIGHTS_CONNECTION_STRING`自動的に設定されます。	`APPLICATIONINSIGHTS_CONNECTION_STRING`
`logger_name`	テレメトリが収集される Python ロガーの名前。	`N/A`
`instrumentation_options`	有効または無効にするインストルメンテーションを決定する入れ子になったディクショナリ。インストルメンテーションは、ライブラリ名によって参照されます。たとえば、 `{"azure_sdk": {"enabled": False}, "flask": {"enabled": False}, "django": {"enabled": True}}` は Azure Core Tracing と Flask インストルメンテーションを無効にしますが、Django とその他の既定のインストルメンテーションは有効のままにします。 `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS`次に説明する環境変数を使用して、インストルメンテーションを無効にすることもできます。	`N/A`

次のような 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 宛てに質問またはコメントをお送りください。

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

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

主要な概念

作業の開始

前提条件

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

使用

Azure Monitor OpenTelemetry Exporter の構成

例

Azure Functionsでの監視

トレースの相関付け

ログの問題

トラブルシューティング

次の手順

共同作成

その他のドキュメント

フィードバック

その他のリソース

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

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

主要な概念

作業の開始

前提条件

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

使用

Azure Monitor OpenTelemetry Exporter の構成

例

Azure Functionsでの監視

トレースの相関付け

ログの問題

トラブルシューティング

次の手順

共同作成

その他のドキュメント

フィードバック

その他のリソース

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