代理配置

该代理高度可配置，可以通过以下方式进行配置：

配置属性

下面是通过配置属性配置代理的示例

opentelemetry-instrument \
    --traces_exporter console,otlp \
    --metrics_exporter console \
    --service_name your-service-name \
    --exporter_otlp_endpoint 0.0.0.0:4317 \
    python myapp.py

以下是对每个配置作用的解释

  • traces_exporter 指定要使用的跟踪导出器。在这种情况下，跟踪被导出到 console (stdout) 和 otlp。otlp 选项告诉 opentelemetry-instrument 将跟踪发送到接受 OTLP (通过 gRPC) 的端点。如果想使用 HTTP 而不是 gRPC，请添加 --exporter_otlp_protocol http/protobuf。有关 traces_exporter 的可用选项的完整列表，请参阅 Python contrib OpenTelemetry Instrumentation。
  • metrics_exporter 指定要使用的指标导出器。在这种情况下，指标被导出到 console (stdout)。目前要求您指定一个指标导出器。如果您不导出指标，请将值指定为 none。
  • service_name 设置与您的遥测数据关联的服务名称，并将该名称发送到您的 可观测性后端。
  • exporter_otlp_endpoint 设置遥测数据导出的端点。如果省略，将使用默认的 Collector 端点，对于 gRPC 为 0.0.0.0:4317，对于 HTTP 为 0.0.0.0:4318。
  • exporter_otlp_headers 根据您选择的可观测性后端是必需的。有关 OTLP 导出器标头的更多信息，请参阅 OTEL_EXPORTER_OTLP_HEADERS。

环境变量

在某些情况下，通过 环境变量 进行配置可能更受青睐。可以使用命令行参数配置的任何设置也可以通过环境变量进行配置。

您可以按照以下步骤确定所需配置属性的正确名称映射

  • 将配置属性转换为大写。
  • 在环境变量前加上 OTEL_ 前缀

例如，exporter_otlp_endpoint 将转换为 OTEL_EXPORTER_OTLP_ENDPOINT。

Python 特定的配置

有一些特定于 Python 的配置选项，您可以通过在环境变量前加上 OTEL_PYTHON_ 来设置它们。

排除的 URL

逗号分隔的正则表达式，表示要跨所有仪表排除的 URL

  • OTEL_PYTHON_EXCLUDED_URLS

您还可以通过使用变量 OTEL_PYTHON_<library>_EXCLUDED_URLS 来为特定仪表排除 URL，其中 library 是以下之一的大写版本：Django、Falcon、FastAPI、Flask、Pyramid、Requests、Starlette、Tornado、urllib、urllib3。

示例

export OTEL_PYTHON_EXCLUDED_URLS="client/.*/info,healthcheck"
export OTEL_PYTHON_URLLIB3_EXCLUDED_URLS="client/.*/info"
export OTEL_PYTHON_REQUESTS_EXCLUDED_URLS="healthcheck"

请求属性名称

将从请求对象中提取并设置为 span 属性的名称的逗号分隔列表。

  • OTEL_PYTHON_DJANGO_TRACED_REQUEST_ATTRS
  • OTEL_PYTHON_FALCON_TRACED_REQUEST_ATTRS
  • OTEL_PYTHON_TORNADO_TRACED_REQUEST_ATTRS

示例

export OTEL_PYTHON_DJANGO_TRACED_REQUEST_ATTRS='path_info,content_type'
export OTEL_PYTHON_FALCON_TRACED_REQUEST_ATTRS='query_string,uri_template'
export OTEL_PYTHON_TORNADO_TRACED_REQUEST_ATTRS='uri,query'

日志记录

有一些配置选项用于控制输出的日志。

  • OTEL_PYTHON_LOG_CORRELATION：启用跟踪上下文注入到日志中 (true, false)
  • OTEL_PYTHON_LOG_FORMAT：指示仪表使用自定义日志格式
  • OTEL_PYTHON_LOG_LEVEL：设置自定义日志级别 (info, error, debug, warning)
  • OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED：启用日志的自动仪表。将 OTLP 处理程序附加到 Python 根记录器。有关示例，请参阅 日志自动仪表。

示例

export OTEL_PYTHON_LOG_CORRELATION=true
export OTEL_PYTHON_LOG_FORMAT="%(msg)s [span_id=%(span_id)s]"
export OTEL_PYTHON_LOG_LEVEL=debug
export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true

其他

还有一些更多的配置选项可以设置，但未归入特定类别。

  • OTEL_PYTHON_DJANGO_INSTRUMENT：设置为 false 以禁用 Django 仪表的默认启用状态
  • OTEL_PYTHON_ELASTICSEARCH_NAME_PREFIX：将 Elasticsearch 操作名称的默认前缀从“Elasticsearch”更改为此处使用的任何名称
  • OTEL_PYTHON_GRPC_EXCLUDED_SERVICES：要从 gRPC 仪表中排除的特定服务的逗号分隔列表
  • OTEL_PYTHON_ID_GENERATOR：指定全局 Tracer Provider 使用的 ID 生成器
  • OTEL_PYTHON_INSTRUMENTATION_SANITIZE_REDIS：启用查询清理
  • OTEL_PYTHON_AUTO_INSTRUMENTATION_EXPERIMENTAL_GEVENT_PATCH：设置为 patch_all 以在初始化 SDK 之前调用 gevent monkeypatch 的 patch_all 方法

示例

export OTEL_PYTHON_DJANGO_INSTRUMENT=false
export OTEL_PYTHON_ELASTICSEARCH_NAME_PREFIX=my-custom-prefix
export OTEL_PYTHON_GRPC_EXCLUDED_SERVICES="GRPCTestServer,GRPCHealthServer"
export OTEL_PYTHON_ID_GENERATOR=xray
export OTEL_PYTHON_INSTRUMENTATION_SANITIZE_REDIS=true
export OTEL_PYTHON_AUTO_INSTRUMENTATION_EXPERIMENTAL_GEVENT_PATCH=patch_all

禁用特定仪表

Python 代理默认会检测 Python 程序的包，并对它能识别的包进行仪表。这使得仪表化变得容易，但也可能导致产生过多或不需要的数据。

您可以使用 OTEL_PYTHON_DISABLED_INSTRUMENTATIONS 环境变量来从仪表中排除特定的包。该环境变量可以设置为要从仪表中排除的仪表入口点名称的逗号分隔列表。大多数情况下，入口点名称与包名相同，并且在包 pyproject.toml 文件的 project.entry-points.opentelemetry_instrumentor 表中设置。

例如，如果您的 Python 程序使用 redis、kafka-python 和 grpc 包，默认情况下，代理将使用 opentelemetry-instrumentation-redis、opentelemetry-instrumentation-kafka-python 和 opentelemetry-instrumentation-grpc 包来仪表它们。要禁用此功能，您可以设置 OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=redis,kafka,grpc_client。


最后修改于 2025 年 9 月 11 日： zero-code/python: document OTEL_PYTHON_AUTO_INSTRUMENTATION_EXPERIMENTAL_GEVENT_PATCH (#7667) (9383da27)