Exporters

处理和导出您的遥测数据

发送遥测数据到 OpenTelemetry Collector，以确保其正确导出。在生产环境中使用 Collector 是一种最佳实践。要可视化您的遥测数据，请将其导出到后端，例如 Jaeger、Zipkin、Prometheus 或特定厂商的后端。

可用导出器

注册表包含一个Python 导出器列表。

在导出器中，OpenTelemetry Protocol (OTLP) 导出器是按照 OpenTelemetry 数据模型设计的，可以无损地发出 OTel 数据。此外，许多处理遥测数据的工具都支持 OTLP（例如 Prometheus、Jaeger 和大多数厂商），为您提供高度的灵活性。要了解更多关于 OTLP 的信息，请参阅 OTLP 规范。

此页面涵盖主要的 OpenTelemetry Python 导出器以及如何设置它们。

注意

如果您使用零代码检测，您可以按照配置指南来学习如何设置导出器。

OTLP

Collector 设置

注意

如果您已经设置了 OTLP collector 或后端，可以跳过此部分，直接设置应用程序的 OTLP 导出器依赖项。

要尝试并验证您的 OTLP 导出器，您可以在一个 Docker 容器中运行 collector，该容器将遥测数据直接写入控制台。

在一个空目录下，创建一个名为 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 容器中运行 collector

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

此 collector 现在可以通过 OTLP 接受遥测数据。稍后，您可能需要配置 collector，以便将其遥测数据发送到您的可观察性后端。

依赖项

如果您想将遥测数据发送到 OTLP 端点（例如 OpenTelemetry Collector、Jaeger 或 Prometheus），您可以在两种不同的协议之间进行选择来传输数据

首先，将相应的导出器包作为您项目的依赖项安装

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

# 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)

控制台

为了调试您的仪器或在开发环境中本地查看值，您可以使用将遥测数据写入控制台（stdout）的导出器。

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

# 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)

注意

每种检测类型都有预设的暂存。这些预设可以通过环境变量 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 来接收跟踪数据。您可以在 Docker 容器中运行 Jaeger，UI 可通过端口 16686 访问，OTLP 可通过端口 4317 和 4318 访问。

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 Receiver 并使用 OTLP 导出器，或者您可以使用 Prometheus 导出器，这是一个 MetricReader，它会启动一个 HTTP 服务器，在请求时收集指标并将其序列化为 Prometheus 文本格式。

后端设置

注意

如果您已经设置了 Prometheus 或与 Prometheus 兼容的后端，可以跳过此部分，并为您的应用程序设置 Prometheus 或 OTLP 导出器依赖项。

您可以按照以下说明，在 Docker 容器中运行 Prometheus，端口 9090 可访问。

创建一个名为 prometheus.yml 的文件，内容如下

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

在 Docker 容器中运行 Prometheus，UI 可通过端口 9090 访问。

docker run --rm -v ${PWD}/prometheus.yml:/prometheus/prometheus.yml -p 9090:9090 prom/prometheus --enable-feature=otlp-write-receive

注意

当使用 Prometheus 的 OTLP Receiver 时，请确保在您的应用程序中将指标的 OTLP 端点设置为 https://:9090/api/v1/otlp。

并非所有 Docker 环境都支持 host.docker.internal。在某些情况下，您可能需要将 host.docker.internal 替换为 localhost 或您机器的 IP 地址。

依赖项

将导出器包作为应用程序的依赖项安装

pip install opentelemetry-exporter-prometheus

更新您的 OpenTelemetry 配置以使用导出器并将数据发送到您的 Prometheus 后端

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)

通过上述配置，您可以访问您的指标，地址为 https://:9464/metrics。Prometheus 或带有 Prometheus receiver 的 OpenTelemetry Collector 可以从此端点抓取指标。

Zipkin

后端设置

注意

如果您已经设置了 Zipkin 或与 Zipkin 兼容的后端，可以跳过此部分，并为您的应用程序设置 Zipkin 导出器依赖项。

您可以通过执行以下命令，在 Docker 容器中运行 Zipkin。

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

依赖项

要将跟踪数据发送到Zipkin，您可以选择两种不同的协议来传输数据

将导出器包安装为应用程序的依赖项。

pip install opentelemetry-exporter-zipkin-proto-http

pip install opentelemetry-exporter-zipkin-json

更新您的 OpenTelemetry 配置以使用该导出器并将数据发送到您的 Zipkin 后端

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="https://: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="https://:9411/api/v2/spans")

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

自定义导出器

最后，您也可以编写自己的导出器。有关更多信息，请参阅 API 文档中的 SpanExporter 接口。

批量发送 Span 和 Log 记录

OpenTelemetry SDK 提供了一组默认的 Span 和 Log 记录处理器，允许您逐个发送 Span（“简单”）或批量发送。建议使用批量发送，但如果您不想批量发送 Span 或 Log 记录，可以改用简单的处理器，如下所示：

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

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

Feedback

这个页面有用吗？

谢谢。您的反馈受到赞赏！

请让我们知道我们如何改进此页面。您的反馈受到赞赏！

最后修改于 2025 年 10 月 29 日：修复暂存首选项环境变量名称 (#8268) (752eac5b)