azure-monitor-opentelemetry-exporter-py

Azure Monitor OpenTelemetry Exporter for Python

Application Insights に OpenTelemetry のトレース、メトリクス、ログを送信するための低レベルエクスポーターです。

インストール

pip install azure-monitor-opentelemetry-exporter

環境変数

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

使用する場面

シナリオ	使用するもの
手早くセットアップして自動計装する	azure-monitor-opentelemetry（ディストリビューション）
カスタムの OpenTelemetry パイプライン	azure-monitor-opentelemetry-exporter（このパッケージ）
テレメトリをきめ細かく制御する	azure-monitor-opentelemetry-exporter（このパッケージ）

エクスポートとプライバシーの境界

テレメトリは Azure に送信され、オフラインストレージにローカル保存される場合もあります。フィールド、エンドポイント、認証情報、保持期間、コストを確認し、エクスポート前にシークレットと個人データをマスキングしてください。グローバルプロバイダーを繰り返しリセットするのではなく、既存のプロバイダーを再利用し、プロセス終了時にプロバイダーをフラッシュしてシャットダウンしてください。以下の個別のスニペットはそれぞれ代替手段であり、まとめて実行する初期化スクリプトではありません。

トレースエクスポーター

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

# Create exporter
exporter = AzureMonitorTraceExporter(
    connection_string="InstrumentationKey=xxx;..."
)

# Configure tracer provider
trace.set_tracer_provider(TracerProvider())
trace.get_tracer_provider().add_span_processor(
    BatchSpanProcessor(exporter)
)

# Use tracer
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("my-span"):
    print("Hello, World!")

メトリクスエクスポーター

from opentelemetry import metrics
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter

# Create exporter
exporter = AzureMonitorMetricExporter(
    connection_string="InstrumentationKey=xxx;..."
)

# Configure meter provider
reader = PeriodicExportingMetricReader(exporter, export_interval_millis=60000)
metrics.set_meter_provider(MeterProvider(metric_readers=[reader]))

# Use meter
meter = metrics.get_meter(__name__)
counter = meter.create_counter("requests_total")
counter.add(1, {"route": "/api/users"})

ログエクスポーター

import logging
from opentelemetry._logs import set_logger_provider
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter

# Create exporter
exporter = AzureMonitorLogExporter(
    connection_string="InstrumentationKey=xxx;..."
)

# Configure logger provider
logger_provider = LoggerProvider()
logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter))
set_logger_provider(logger_provider)

# Add handler to Python logging
handler = LoggingHandler(level=logging.INFO, logger_provider=logger_provider)
logging.getLogger().addHandler(handler)

# Use logging
logger = logging.getLogger(__name__)
logger.info("This will be sent to Application Insights")

環境変数から取得

エクスポーターは APPLICATIONINSIGHTS_CONNECTION_STRING を自動的に読み取ります。

from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

# Connection string from environment
exporter = AzureMonitorTraceExporter()

Azure AD 認証

from azure.identity import DefaultAzureCredential
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

exporter = AzureMonitorTraceExporter(
    credential=DefaultAzureCredential()
)

サンプリング

一貫したサンプリングには ApplicationInsightsSampler を使用します。

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.sampling import ParentBasedTraceIdRatio
from azure.monitor.opentelemetry.exporter import ApplicationInsightsSampler

# Sample 10% of traces
sampler = ApplicationInsightsSampler(sampling_ratio=0.1)

trace.set_tracer_provider(TracerProvider(sampler=sampler))

オフラインストレージ

再試行のためにオフラインストレージを構成します。

from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

exporter = AzureMonitorTraceExporter(
    connection_string="...",
    storage_directory="/path/to/storage",  # Custom storage path
    disable_offline_storage=False  # Enable retry (default)
)

オフラインストレージを無効化

exporter = AzureMonitorTraceExporter(
    connection_string="...",
    disable_offline_storage=True  # Disable disk persistence; transport retry behavior is separate
)

ソブリンクラウド

from azure.identity import AzureAuthorityHosts, DefaultAzureCredential
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

# Azure Government
credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
exporter = AzureMonitorTraceExporter(
    connection_string="InstrumentationKey=xxx;IngestionEndpoint=https://xxx.in.applicationinsights.azure.us/",
    credential=credential
)

エクスポーターの種類

エクスポーター	テレメトリの種類	Application Insights のテーブル
AzureMonitorTraceExporter	トレース／スパン	requests、dependencies、exceptions
AzureMonitorMetricExporter	メトリクス	customMetrics、performanceCounters
AzureMonitorLogExporter	ログ	traces、customEvents

構成オプション

パラメーター	説明	デフォルト
connection_string	Application Insights の接続文字列	環境変数から取得
credential	AAD 認証用の Azure 認証情報	なし
disable_offline_storage	再試行用ストレージを無効化	False
storage_directory	カスタムストレージのパス	一時ディレクトリ

ベストプラクティス

1. 本番環境では BatchSpanProcessor を使用します（SimpleSpanProcessor ではなく）。
2. サービス間で一貫したサンプリングを行うには ApplicationInsightsSampler を使用します。
3. 本番環境での信頼性を高めるため、オフラインストレージを有効化します。
4. インストルメンテーションキーではなく、AAD 認証を使用します。
5. ワークロードに適した エクスポート間隔を設定します。
6. カスタムパイプラインが必要な場合を除き、ディストリビューション（azure-monitor-opentelemetry）を使用します。

制限事項

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