Exporters

In order to visualize and analyze your telemetry, you will need to export your data to an OpenTelemetry Collector or a backend such as Jaeger, Zipkin, Prometheus or a vendor-specific one.

As part of OpenTelemetry Python you will find many exporters being available. Among them, the OpenTelemetry Protocol (OTLP) exporters provide the best experience for you as an end-user, since it is a general-purpose telemetry data delivery protocol designed in the scope of the OpenTelemetry project.

To learn more about the OTLP protocol, you can read the OTLP Specification.

Below you will find some introductions on how to set up exporters for OTLP and other common protocols in your code.

控制台导出器

控制台导出器适用于开发和调试任务，是设置最简单的导出器。

跟踪

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

# 大多数后端需要服务名，尽管控制台导出不需要，最好还是设置服务名。
resource = Resource(attributes={
    SERVICE_NAME: "your-service-name"
})

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

# 开始跟踪！

指标

使用 PeriodicExportingMetricReader 可以定期将指标打印到控制台。PeriodicExportingMetricReader 可以配置以不同的时间间隔导出，为每个仪表类型更改temporality，或更改每个仪表类型的默认聚合方式。

时间性预设

对于每种仪表类型都有时间性预设。可以通过环境变量 OTEL_EXPORTER_METRICS_TEMPORALITY_PREFERENCE 进行设置，例如：

export OTEL_EXPORTER_METRICS_TEMPORALITY_PREFERENCE="DELTA"

OTEL_EXPORTER_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_METRICS_TEMPORALITY_PREFERENCE 设置为除 CUMULATIVE、DELTA 或 LOWMEMORY 以外的任何值都会记录一个警告，并将此环境变量设置为 CUMULATIVE。

from opentelemetry import metrics
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader, ConsoleMetricExporter
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

# 大多数后端需要服务名，尽管控制台导出不需要，最好还是设置服务名。
resource = Resource(attributes={
    SERVICE_NAME: "your-service-name"
})

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

OTLP 终端节点或收集器

要将数据发送到 OTLP 终端节点或者 OpenTelemetry 收集器，您需要配置一个 OTLP 导出器，将数据发送到您的终端节点。

首先，安装 OTLP 导出器：

pip install opentelemetry-exporter-otlp-proto-grpc

跟踪

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import SERVICE_NAME, Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# 大多数后端需要服务名
resource = Resource(attributes={
    SERVICE_NAME: "your-service-name"
})

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

# 开始跟踪！

指标

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
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

# 大多数后端需要服务名
resource = Resource(attributes={
    SERVICE_NAME: "your-service-name"
})

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

使用 HTTP

如果您希望使用 OTLP/HTTP 和二进制编码的 protobuf 格式，可以安装该软件包：

pip install opentelemetry-exporter-otlp-proto-http

接下来，将 import 声明替换为以下内容：

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

最后，如果您在代码中指定端点，则更新您的导出器端点：

OTLPSpanExporter(endpoint="<traces-endpoint>/v1/traces")

目前没有 OTLP/HTTP 指标导出器。

Jaeger

Jaeger 原生支持 OTLP。请参照上述设置 OTLP 导出器 的说明。然后在容器中运行 Jaeger，UI 可以通过端口 16686 访问，OTLP 在端口 4137 和 4138 开启：

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

Zipkin

如果您使用 Zipkin 来可视化跟踪数据，您需要首先设置它。以下是在 Docker 容器中运行 Zipkin 的方法：

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

接下来，安装 Zipkin 导出器软件包：

pip install opentelemetry-exporter-zipkin-proto-http

然后在初始化跟踪时配置导出器：

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

# 开始跟踪！

使用 JSON

如果您希望将 Thrift 作为协议使用，可以安装该软件包：

pip install opentelemetry-exporter-zipkin-json

并将 ZipkinExporter 的 import 声明替换为以下内容：

from opentelemetry.exporter.zipkin.json import ZipkinExporter

Prometheus

如果您正在使用 Prometheus 收集指标数据，您需要首先设置它。

首先，创建一个配置文件：

cat > prometheus.yml <<EOF
scrape_configs:
  - job_name: 'otel-python-demo'
    scrape_interval: 5s
    static_configs:
      - targets: ['localhost:8000']
EOF

然后在 Docker 中启动 Prometheus 服务器：

docker run -d --rm \
    --network=host \
    -v $(pwd)/prometheus.yml:/etc/prometheus/prometheus.yml \
    prom/prometheus

接下来，安装 Prometheus 导出器软件包：

pip install opentelemetry-exporter-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.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

# 大多数后端需要服务名
resource = Resource(attributes={
    SERVICE_NAME: "your-service-name"
})

# 启动 Prometheus 客户端
start_http_server(port=8000, addr="localhost")
# 初始化 PrometheusMetricReader，从 SDK 按需拉取指标以响应抓取请求
reader = PrometheusMetricReader()
provider = MeterProvider(resource=resource, metric_readers=[reader])
metrics.set_meter_provider(provider)
最后修改 December 10, 2023: translate (a4350d6e)