エクスポーター

テレメトリーデータの処理とエクスポート

OpenTelemetryコレクターにテレメトリーを送信し、正しくエクスポートされることを確認してください。本番環境でコレクターを使用することはベストプラクティスです。テレメトリーを可視化するために、Jaeger、Zipkin、 Prometheus、またはベンダー固有のようなバックエンドにエクスポートしてください。

使用可能なエクスポーター

レジストリには、Python 用のエクスポーターのリストが含まれています。

エクスポーターの中でも、OpenTelemetry Protocol (OTLP)エクスポーターは、OpenTelemetryのデータモデルを考慮して設計されており、OTelデータを情報の損失なく出力します。さらに、多くのテレメトリーデータを扱うツールがOTLPに対応しており（たとえば、Prometheus、Jaegerやほとんどのベンダー）、必要なときに高い柔軟性を提供します。 OTLPについて詳細に学習したい場合は、OTLP仕様を参照してください。

このページでは、主要なOpenTelemetry Python エクスポーターとその設定方法について説明します。

Note

ゼロコード計装を使用している場合は、設定ガイドに従ってエクスポーターの設定方法を学ぶことができます。

OTLP

コレクターのセットアップ

Note

OTLPコレクターまたはバックエンドがすでにセットアップされている場合は、このセクションをスキップして、アプリケーション用のOTLPエクスポーター依存関係のセットアップに進むことができます。

OTLPエクスポーターを試し、検証するために、テレメトリーを直接コンソールに書き込むDockerコンテナでコレクターを実行できます。空のディレクトリで、以下の内容でcollector-config.yamlというファイルを作成します。

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
exporters:
  debug:
    verbosity: detailed
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      exporters: [debug]
    logs:
      receivers: [otlp]
      exporters: [debug]

次に、Docker コンテナでコレクターを実行します。

docker run -p 4317:4317 -p 4318:4318 --rm -v $(pwd)/collector-config.yaml:/etc/otelcol/config.yaml otel/opentelemetry-collector

このコレクターは、OTLPを介してテレメトリーを受け取ることができるようになりました。後で、テレメトリーを監視バックエンドに送信するためにコレクターを設定することもできます。

依存関係

テレメトリーデータをOTLPエンドポイント（OpenTelemetryコレクター、Jaeger、Prometheusなど）に送信したい場合、データを転送するために2つの異なるプロトコルから選択できます。

まず、プロジェクトの依存関係として対応するエクスポーターパッケージをインストールします。

pip install opentelemetry-exporter-otlp-proto-http

pip install opentelemetry-exporter-otlp-proto-grpc

使用法

次に、コード内でOTLPエンドポイントを指すようにエクスポーターを設定します。

from opentelemetry.sdk.resources import SERVICE_NAME, Resource

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

from opentelemetry import metrics
from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader

# ほとんどのバックエンドではサービス名が必要です
resource = Resource.create(attributes={
    SERVICE_NAME: "your-service-name"
})

tracerProvider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(OTLPSpanExporter(endpoint="<traces-endpoint>/v1/traces"))
tracerProvider.add_span_processor(processor)
trace.set_tracer_provider(tracerProvider)

reader = PeriodicExportingMetricReader(
    OTLPMetricExporter(endpoint="<traces-endpoint>/v1/metrics")
)
meterProvider = MeterProvider(resource=resource, metric_readers=[reader])
metrics.set_meter_provider(meterProvider)

from opentelemetry.sdk.resources import SERVICE_NAME, Resource

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

from opentelemetry import metrics
from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader

# ほとんどのバックエンドではサービス名が必要です
resource = Resource.create(attributes={
    SERVICE_NAME: "your-service-name"
})

tracerProvider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(OTLPSpanExporter(endpoint="your-endpoint-here"))
tracerProvider.add_span_processor(processor)
trace.set_tracer_provider(tracerProvider)

reader = PeriodicExportingMetricReader(
    OTLPMetricExporter(endpoint="localhost:5555")
)
meterProvider = MeterProvider(resource=resource, metric_readers=[reader])
metrics.set_meter_provider(meterProvider)

コンソール

計装をデバッグしたり、開発環境でローカルに値を確認したりするために、テレメトリーデータをコンソール（標準出力）に書き込むエクスポーターを使用できます。

ConsoleSpanExporterとConsoleMetricExporterはopentelemetry-sdkパッケージに含まれています。

from opentelemetry.sdk.resources import SERVICE_NAME, Resource

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter

from opentelemetry import metrics
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader, ConsoleMetricExporter

# ほとんどのバックエンドではサービス名が必要です。
# コンソールエクスポートには必須ではありませんが、
# いずれにしてもサービス名を設定しておくとよいでしょう。
resource = Resource.create(attributes={
    SERVICE_NAME: "your-service-name"
})

tracerProvider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(ConsoleSpanExporter())
tracerProvider.add_span_processor(processor)
trace.set_tracer_provider(tracerProvider)

reader = PeriodicExportingMetricReader(ConsoleMetricExporter())
meterProvider = MeterProvider(resource=resource, metric_readers=[reader])
metrics.set_meter_provider(meterProvider)

注記

各計装種別には集約時間性のプリセットがあります。これらのプリセットは、たとえば次のように環境変数OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCEで設定できます。

export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE="DELTA"

OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCEのデフォルト値は"CUMULATIVE"です。

この環境変数で使用可能な値と対応する設定は次のとおりです。

CUMULATIVE
- Counter: CUMULATIVE
- UpDownCounter: CUMULATIVE
- Histogram: CUMULATIVE
- ObservableCounter: CUMULATIVE
- ObservableUpDownCounter: CUMULATIVE
- ObservableGauge: CUMULATIVE
DELTA
- Counter: DELTA
- UpDownCounter: CUMULATIVE
- Histogram: DELTA
- ObservableCounter: DELTA
- ObservableUpDownCounter: CUMULATIVE
- ObservableGauge: CUMULATIVE
LOWMEMORY
- Counter: DELTA
- UpDownCounter: CUMULATIVE
- Histogram: DELTA
- ObservableCounter: CUMULATIVE
- ObservableUpDownCounter: CUMULATIVE
- ObservableGauge: CUMULATIVE

OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCEをCUMULATIVE、DELTA、LOWMEMORY以外の値に設定すると、警告がログに記録され、この環境変数はCUMULATIVEに設定されます。

Jaeger

バックエンドのセットアップ

Jaegerは、トレースデータを受信するためにOTLPをネイティブでサポートしています。UIがポート16686でアクセス可能で、OTLPがポート4317と4318で有効になったDockerコンテナでJaegerを実行できます。

docker run --rm \
  -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 9411:9411 \
  jaegertracing/all-in-one:latest

使用方法

OTLPエクスポーターをセットアップするための手順に従ってください。

Prometheus

メトリクスデータをPrometheusに送信するには、PrometheusのOTLPレシーバーを有効にして OTLPエクスポーターを使用するか、Prometheusエクスポーターを使用できます。 Prometheusエクスポーターは、メトリクスを収集しリクエストに応じてPrometheusテキスト形式にシリアライズするHTTPサーバーを起動するMetricReaderです。

バックエンドのセットアップ

注意

すでにPrometheusまたはPrometheus互換のバックエンドをセットアップしている場合は、このセクションをスキップして、アプリケーション用のPrometheusまたはOTLPエクスポーターの依存関係をセットアップしてください。

PrometheusをDockerコンテナで実行し、ポート9090でアクセスできるようにするには、以下の手順に従ってください。

以下の内容でprometheus.ymlというファイルを作成します。

scrape_configs:
  - job_name: dice-service
    scrape_interval: 5s
    static_configs:
      - targets: [host.docker.internal:9464]

UIがポート9090でアクセス可能なDockerコンテナでPrometheusを実行します。

docker run --rm -v ${PWD}/prometheus.yml:/prometheus/prometheus.yml -p 9090:9090 prom/prometheus --web.enable-otlp-receiver

注意

PrometheusのOTLPレシーバーを使用する場合は、アプリケーションでメトリクス用のOTLPエンドポイントをhttp://localhost:9090/api/v1/otlpに設定してください。

すべてのDocker環境がhost.docker.internalをサポートしているわけではありません。場合によっては、host.docker.internalをlocalhostまたはマシンのIPアドレスに置き換える必要があるかもしれません。

依存関係

アプリケーションの依存関係としてエクスポーターパッケージをインストールします。

pip install opentelemetry-exporter-prometheus

エクスポーターを使用し、Prometheusバックエンドにデータを送信するようにOpenTelemetry設定を更新します。

from prometheus_client import start_http_server

from opentelemetry import metrics
from opentelemetry.exporter.prometheus import PrometheusMetricReader
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

# ほとんどのバックエンドではサービス名が必要です
resource = Resource.create(attributes={
    SERVICE_NAME: "your-service-name"
})

# Prometheusクライアントを起動します
start_http_server(port=9464, addr="localhost")
# スクレイプリクエストに応答するために、SDKからメトリクスを
# オンデマンドで取得するPrometheusMetricReaderを初期化します
reader = PrometheusMetricReader()
provider = MeterProvider(resource=resource, metric_readers=[reader])
metrics.set_meter_provider(provider)

上記の設定により、http://localhost:9464/metricsでメトリクスにアクセスできます。 PrometheusまたはPrometheusレシーバーを持つOpenTelemetryコレクターが、このエンドポイントからメトリクスをスクレイプできます。

Zipkin

バックエンドのセットアップ

注意

すでにZipkinまたはZipkin互換のバックエンドをセットアップしている場合は、このセクションをスキップして、アプリケーション用のZipkinエクスポーターの依存関係をセットアップしてください。

以下のコマンドを実行して、ZipkinをDockerコンテナで実行できます。

docker run --rm -d -p 9411:9411 --name zipkin openzipkin/zipkin

依存関係

トレースデータをZipkinに送信したい場合、データを転送するために2つの異なるプロトコルから選択できます。

アプリケーションの依存関係としてエクスポーターパッケージをインストールします。

pip install opentelemetry-exporter-zipkin-proto-http

pip install opentelemetry-exporter-zipkin-json

エクスポーターを使用し、Zipkinバックエンドにデータを送信するようにOpenTelemetry設定を更新します。

from opentelemetry import trace
from opentelemetry.exporter.zipkin.proto.http import ZipkinExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

resource = Resource.create(attributes={
    SERVICE_NAME: "your-service-name"
})

zipkin_exporter = ZipkinExporter(endpoint="http://localhost:9411/api/v2/spans")

provider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(zipkin_exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

from opentelemetry import trace
from opentelemetry.exporter.zipkin.json import ZipkinExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

resource = Resource.create(attributes={
    SERVICE_NAME: "your-service-name"
})

zipkin_exporter = ZipkinExporter(endpoint="http://localhost:9411/api/v2/spans")

provider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(zipkin_exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

カスタムエクスポーター

最後に、独自のエクスポーターを作成することもできます。詳細については、APIドキュメントのSpanExporterインターフェイスを参照してください。

スパンとログレコードのバッチ処理

OpenTelemetry SDKは、スパンを1つずつ発行する（「シンプル」）か、バッチで発行するかを選択できるデフォルトのスパンプロセッサーとログレコードプロセッサーのセットを提供しています。バッチ処理の使用が推奨されますが、スパンやログレコードをバッチ処理したくない場合は、かわりに以下のようにシンプルプロセッサーを使用できます。

from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import SimpleSpanProcessor

processor = SimpleSpanProcessor(OTLPSpanExporter(endpoint="your-endpoint-here"))

フィードバック

このページは役に立ちましたか?

Thank you. Your feedback is appreciated!

Please let us know how we can improve this page. Your feedback is appreciated!

最終更新 May 5, 2026: [ja] docs(i18n): Translate content/en/docs/languages/python/exporters.md (#9809) (449c9668)