azure-monitor-opentelemetry-py

Python 向け Azure Monitor OpenTelemetry Distro

OpenTelemetry の自動計装を使用して、Application Insights をワンラインでセットアップします。

インストール

pip install azure-monitor-opentelemetry

環境変数

APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=xxx;IngestionEndpoint=https://xxx.in.applicationinsights.azure.com/

クイックスタート

from azure.monitor.opentelemetry import configure_azure_monitor

# One-line setup - reads connection string from environment
configure_azure_monitor()

# Your application code...

明示的な構成

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
    connection_string="InstrumentationKey=xxx;IngestionEndpoint=https://xxx.in.applicationinsights.azure.com/"
)

Flask を使用する場合

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

configure_azure_monitor()

app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello, World!"

if __name__ == "__main__":
    app.run()

Django を使用する場合

# settings.py
from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor()

# Django settings...

FastAPI を使用する場合

from fastapi import FastAPI
from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor()

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

カスタムトレース

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

configure_azure_monitor()

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("my-operation") as span:
    span.set_attribute("custom.attribute", "value")
    # Do work...

カスタムメトリクス

from opentelemetry import metrics
from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor()

meter = metrics.get_meter(__name__)
counter = meter.create_counter("my_counter")

counter.add(1, {"dimension": "value"})

カスタムログ

import logging
from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor()

logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)

logger.info("This will appear in Application Insights")
logger.error("Errors are captured too", exc_info=True)

サンプリング

from azure.monitor.opentelemetry import configure_azure_monitor

# Sample 10% of requests
configure_azure_monitor(
    sampling_ratio=0.1
)

クラウドロール名

Application Map のクラウドロール名を設定します。

from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry.sdk.resources import Resource, SERVICE_NAME

configure_azure_monitor(
    resource=Resource.create({SERVICE_NAME: "my-service-name"})
)

特定の計装を無効にする

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
    instrumentation_options={"flask": {"enabled": False}}  # Disable Flask; others keep defaults
)

ライブメトリクスを有効にする

from azure.monitor.opentelemetry import configure_azure_monitor

configure_azure_monitor(
    enable_live_metrics=True
)

Azure AD 認証

from azure.monitor.opentelemetry import configure_azure_monitor
from azure.identity import DefaultAzureCredential

configure_azure_monitor(
    credential=DefaultAzureCredential()
)

プロセスごとに一度だけ構成してください。インストールしたディストリビューションのバージョンを固定し、内容を確認してください。サポート対象のライブラリとデフォルト設定は変更される可能性があり、Azure Monitor と Microsoft OpenTelemetry のディストリビューションでは異なる API が使用されます。両方を初期化しないでください。Azure SDK のリファレンスでは instrumentation_options が説明されています。以下のすべてのライブラリが含まれていると決めつけず、オプションの計装と依存関係を確認してください。テレメトリはプロセスの外部に送信されます。送信先と保持期間を承認し、ログやスパンから秘密情報や個人データを除去し、カーディナリティと取り込みコストを抑え、合成データを使ってエクスポートを検証してください。トレースのサンプリングが、メトリクスやすべてのログのサンプリングを意味するわけではありません。

含まれる自動計装

ライブラリ	テレメトリの種類
Flask	トレース
Django	トレース
FastAPI	トレース
Requests	トレース
urllib3	トレース
httpx	トレース
aiohttp	トレース
psycopg2	トレース
pymysql	トレース
pymongo	トレース
redis	トレース

構成オプション

パラメーター	説明	デフォルト
connection_string	Application Insights の接続文字列	環境変数から取得
credential	AAD 認証用の Azure 資格情報	なし
sampling_ratio	明示的なトレースのサンプリング比率	バージョンによって異なります。サンプラー／環境を確認してください
resource	OpenTelemetry リソース	自動検出
instrumentation_options	ライブラリごとの有効／無効を指定する辞書	バージョンによって異なります
enable_live_metrics	ライブメトリクスストリームを有効にする	バージョンによって異なります。明示的に設定してください

ベストプラクティス

1. configure_azure_monitor() を早い段階で呼び出す — 計装対象のライブラリをインポートする前に呼び出してください
2. 本番環境では、接続文字列に環境変数を使用する
3. マルチサービスアプリケーションでは、クラウドロール名を設定する
4. トラフィックの多いアプリケーションでは、サンプリングを有効にする
5. ログ分析クエリを改善するために、構造化ログを使用する
6. デバッグを改善するために、スパンにカスタム属性を追加する
7. 本番ワークロードでは、AAD 認証を使用する

使用する場面

このスキルは、概要で説明されているワークフローやアクションを実行する場合に適用できます。

制限事項

• 上記で説明されている範囲にタスクが明確に一致する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功条件が不足している場合は、作業を中断して確認を求めてください。