Exporters

Process and export your telemetry data

You are viewing the English version of this page because it has not yet been fully translated. Interested in helping out? See Contributing.

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

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

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

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

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

Note

[ゼロコード計装](/docs/zero-code/{{ $l }})を使用している場合は、[設定ガイド](/docs/zero-code/{{ $l }}/configuration/)に従ってエクスポーターの設定方法を学ぶことができます。

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

Dependencies

If you want to send telemetry data to an OTLP endpoint (like the OpenTelemetry Collector, Jaeger or Prometheus), you can choose between two different protocols to transport your data:

Start by installing the respective exporter packages as a dependency for your project:

pip install opentelemetry-exporter-otlp-proto-http

pip install opentelemetry-exporter-otlp-proto-grpc

Usage

Next, configure the exporter to point at an OTLP endpoint in your code.

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

# Service name is required for most backends
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

# Service name is required for most backends
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)

Console

To debug your instrumentation or see the values locally in development, you can use exporters writing telemetry data to the console (stdout).

The ConsoleSpanExporter and ConsoleMetricExporter are included in the opentelemetry-sdk package.

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

# Service name is required for most backends,
# and although it's not necessary for console export,
# it's good to set service name anyways.
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)

Note

There are temporality presets for each instrumentation kind. These presets can be set with the environment variable OTEL_EXPORTER_METRICS_TEMPORALITY_PREFERENCE, for example:

export OTEL_EXPORTER_METRICS_TEMPORALITY_PREFERENCE="DELTA"

The default value for OTEL_EXPORTER_METRICS_TEMPORALITY_PREFERENCE is "CUMULATIVE".

The available values and their corresponding settings for this environment variable are:

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

Setting OTEL_EXPORTER_METRICS_TEMPORALITY_PREFERENCE to any other value than CUMULATIVE, DELTA or LOWMEMORY will log a warning and set this environment variable to 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 --enable-feature=otlp-write-receive

注意

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

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

Dependencies

Install the exporter package as a dependency for your application:

pip install opentelemetry-exporter-prometheus

Update your OpenTelemetry configuration to use the exporter and to send data to your Prometheus backend:

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

# Service name is required for most backends
resource = Resource.create(attributes={
    SERVICE_NAME: "your-service-name"
})

# Start Prometheus client
start_http_server(port=9464, addr="localhost")
# Initialize PrometheusMetricReader which pulls metrics from the SDK
# on-demand to respond to scrape requests
reader = PrometheusMetricReader()
provider = MeterProvider(resource=resource, metric_readers=[reader])
metrics.set_meter_provider(provider)

With the above you can access your metrics at http://localhost:9464/metrics. Prometheus or an OpenTelemetry Collector with the Prometheus receiver can scrape the metrics from this endpoint.

Zipkin

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

注意

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

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

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

Dependencies

To send your trace data to Zipkin, you can choose between two different protocols to transport your data:

Install the exporter package as a dependency for your application:

pip install opentelemetry-exporter-zipkin-proto-http

pip install opentelemetry-exporter-zipkin-json

Update your OpenTelemetry configuration to use the exporter and to send data to your Zipkin backend:

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!

最終更新 June 11, 2025: Alert cleanup (#7090) (c392c714)