Python 配置说明

配置参数

全部配置信息如下：

参数名	环境变量名	描述
--logs_exporter	OTEL_LOGS_EXPORTER	日志导出器
--metrics_exporter	OTEL_METRICS_EXPORTER	指标导出器
--propagators	OTEL_PROPAGATORS	传播器
--context	OTEL_CONTEXT	上下文
--id_generator	OTEL_ID_GENERATOR	ID 生成器
--meter_provider	OTEL_METER_PROVIDER	仪表提供者
--tracer_provider	OTEL_TRACER_PROVIDER	跟踪器提供者
--traces_exporter	OTEL_TRACES_EXPORTER	跟踪导出器
--configurator	OTEL_CONFIGURATOR	配置器
--disabled_instrumentations	OTEL_DISABLED_INSTRUMENTATIONS	禁用的仪器
--distro	OTEL_DISTRO	发行版
--attribute_count_limit	OTEL_ATTRIBUTE_COUNT_LIMIT	属性数量限制
--attribute_value_length_limit	OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT	属性值长度限制
--blrp_export_timeout	OTEL_BLRP_EXPORT_TIMEOUT	BLRP 导出超时
--blrp_max_export_batch_size	OTEL_BLRP_MAX_EXPORT_BATCH_SIZE	BLRP 最大导出批量大小
--blrp_max_queue_size	OTEL_BLRP_MAX_QUEUE_SIZE	BLRP 最大队列大小
--blrp_schedule_delay	OTEL_BLRP_SCHEDULE_DELAY	BLRP 调度延迟
--bsp_export_timeout	OTEL_BSP_EXPORT_TIMEOUT	BSP 导出超时
--bsp_max_export_batch_size	OTEL_BSP_MAX_EXPORT_BATCH_SIZE	BSP 最大导出批量大小
--bsp_max_queue_size	OTEL_BSP_MAX_QUEUE_SIZE	BSP 最大队列大小
--bsp_schedule_delay	OTEL_BSP_SCHEDULE_DELAY	BSP 调度延迟
--event_attribute_count_limit	OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT	事件属性数量限制
--experimental_resource_detectors	OTEL_EXPERIMENTAL_RESOURCE_DETECTORS	实验性资源检测器
--exporter_otlp_certificate	OTEL_EXPORTER_OTLP_CERTIFICATE	OTLP 证书
--exporter_otlp_client_certificate	OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE	OTLP 客户端证书
--exporter_otlp_client_key	OTEL_EXPORTER_OTLP_CLIENT_KEY	OTLP 客户端密钥
--exporter_otlp_compression	OTEL_EXPORTER_OTLP_COMPRESSION	OTLP 压缩
--exporter_otlp_endpoint	OTEL_EXPORTER_OTLP_ENDPOINT	OTLP 端点
--exporter_otlp_headers	OTEL_EXPORTER_OTLP_HEADERS	OTLP 头信息
--exporter_otlp_insecure	OTEL_EXPORTER_OTLP_INSECURE	OTLP 不安全
--exporter_otlp_logs_certificate	OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE	OTLP 日志证书
--exporter_otlp_logs_client_certificate	OTEL_EXPORTER_OTLP_LOGS_CLIENT_CERTIFICATE	OTLP 日志客户端证书
--exporter_otlp_logs_client_key	OTEL_EXPORTER_OTLP_LOGS_CLIENT_KEY	OTLP 日志客户端密钥
--exporter_otlp_logs_compression	OTEL_EXPORTER_OTLP_LOGS_COMPRESSION	OTLP 日志压缩
--exporter_otlp_logs_endpoint	OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	OTLP 日志端点
--exporter_otlp_logs_headers	OTEL_EXPORTER_OTLP_LOGS_HEADERS	OTLP 日志头信息
--exporter_otlp_logs_insecure	OTEL_EXPORTER_OTLP_LOGS_INSECURE	OTLP 日志不安全
--exporter_otlp_logs_protocol	OTEL_EXPORTER_OTLP_LOGS_PROTOCOL	OTLP 日志协议
--exporter_otlp_logs_timeout	OTEL_EXPORTER_OTLP_LOGS_TIMEOUT	OTLP 日志超时
--exporter_otlp_metrics_certificate	OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE	OTLP 指标证书
--exporter_otlp_metrics_client_certificate	OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE	OTLP 指标客户端证书
--exporter_otlp_metrics_client_key	OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY	OTLP 指标客户端密钥
--exporter_otlp_metrics_compression	OTEL_EXPORTER_OTLP_METRICS_COMPRESSION	OTLP 指标压缩
--exporter_otlp_metrics_default_histogram_aggregation	OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION	OTLP 指标默认直方图聚合
--exporter_otlp_metrics_endpoint	OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	OTLP 指标端点
--exporter_otlp_metrics_headers	OTEL_EXPORTER_OTLP_METRICS_HEADERS	OTLP 指标头信息
--exporter_otlp_metrics_insecure	OTEL_EXPORTER_OTLP_METRICS_INSECURE	OTLP 指标不安全
--exporter_otlp_metrics_protocol	OTEL_EXPORTER_OTLP_METRICS_PROTOCOL	OTLP 指标协议
--exporter_otlp_metrics_temporality_preference	OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE	OTLP 指标时间偏好
--exporter_otlp_metrics_timeout	OTEL_EXPORTER_OTLP_METRICS_TIMEOUT	OTLP 指标超时
--exporter_otlp_protocol	OTEL_EXPORTER_OTLP_PROTOCOL	OTLP 协议
--exporter_otlp_timeout	OTEL_EXPORTER_OTLP_TIMEOUT	OTLP 超时
--exporter_otlp_traces_certificate	OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE	OTLP 跟踪证书
--exporter_otlp_traces_client_certificate	OTEL_EXPORTER_OTLP_TRACES_CLIENT_CERTIFICATE	OTLP 跟踪客户端证书
--exporter_otlp_traces_client_key	OTEL_EXPORTER_OTLP_TRACES_CLIENT_KEY	OTLP 跟踪客户端密钥
--exporter_otlp_traces_compression	OTEL_EXPORTER_OTLP_TRACES_COMPRESSION	OTLP 跟踪压缩
--exporter_otlp_traces_endpoint	OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	OTLP 跟踪端点
--exporter_otlp_traces_headers	OTEL_EXPORTER_OTLP_TRACES_HEADERS	OTLP 跟踪头信息
--exporter_otlp_traces_insecure	OTEL_EXPORTER_OTLP_TRACES_INSECURE	OTLP 跟踪不安全
--exporter_otlp_traces_protocol	OTEL_EXPORTER_OTLP_TRACES_PROTOCOL	OTLP 跟踪协议
--exporter_otlp_traces_timeout	OTEL_EXPORTER_OTLP_TRACES_TIMEOUT	OTLP 跟踪超时
--exporter_prometheus_host	OTEL_EXPORTER_PROMETHEUS_HOST	Prometheus 主机
--exporter_prometheus_port	OTEL_EXPORTER_PROMETHEUS_PORT	Prometheus 端口
--link_attribute_count_limit	OTEL_LINK_ATTRIBUTE_COUNT_LIMIT	链接属性数量限制
--log_level	OTEL_LOG_LEVEL	日志级别
--metrics_exemplar_filter	OTEL_METRICS_EXEMPLAR_FILTER	指标示例过滤器
--metric_export_interval	OTEL_METRIC_EXPORT_INTERVAL	指标导出间隔
--metric_export_timeout	OTEL_METRIC_EXPORT_TIMEOUT	指标导出超时
--resource_attributes	OTEL_RESOURCE_ATTRIBUTES	资源属性
--sdk_disabled	OTEL_SDK_DISABLED	SDK 禁用
--service_name	OTEL_SERVICE_NAME	服务名称
--span_attribute_count_limit	OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT	跨度属性数量限制
--span_attribute_value_length_limit	OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT	跨度属性值长度限制
--span_event_count_limit	OTEL_SPAN_EVENT_COUNT_LIMIT	跨度事件数量限制
--span_link_count_limit	OTEL_SPAN_LINK_COUNT_LIMIT	跨度链接数量限制
--traces_sampler	OTEL_TRACES_SAMPLER	跟踪采样器
--traces_sampler_arg	OTEL_TRACES_SAMPLER_ARG	跟踪采样器参数
--version	OTEL_VERSION	版本信息

环境变量

在某些情况下，通过环境变量进行配置更为优选。任何可以通过命令行参数配置的设置也可以通过环境变量进行配置。

您可以应用以下步骤来确定所需配置属性的正确名称映射：

• 将配置属性转换为大写。
• 在环境变量前加上 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"

请求属性名称

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

• 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 提供程序的 ID 生成器
• OTEL_PYTHON_INSTRUMENTATION_SANITIZE_REDIS：启用查询清理

示例：

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

禁用特定仪器

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。