Agent配置

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

配置属性

以下是通过配置属性进行代理配置的示例：

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（标准输出）和 otlp。otlp 选项告诉 opentelemetry-instrument 将跟踪发送到接受 OTLP 的 gRPC 端点。要使用 HTTP 而不是 gRPC，请添加 --exporter_otlp_protocol http。有关 traces_exporter 的可用选项的完整列表，请参阅 Python 贡献库中的 OpenTelemetry Instrumentation。
  • metrics_exporter 指定要使用的指标导出器。在本例中，指标被导出到 console（标准输出）。当前需要为指标导出器指定值。如果不导出指标，请将值指定为 none。
  • service_name 设置与您的遥测相关联的服务的名称，并发送到您的 可观察性后端。
  • exporter_otlp_endpoint 设置导出遥测的端点。如果省略，将使用默认的 Collector 端点，即 gRPC 的 0.0.0.0:4317 和 HTTP 的 0.0.0.0:4318。
  • exporter_otlp_headers 根据所选择的可观察性后端而需求。有关更多信息，请参阅 这里。

环境变量

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

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

  • 将配置属性转换为大写。
  • 使用 OTEL_ 作为环境变量的前缀。

例如，exporter_otlp_endpoint 将转换为 OTEL_EXPORTER_OTLP_ENDPOINT。

特定于Python的配置

您可以通过在环境变量中使用 OTEL_PYTHON_ 作为前缀来设置一些特定于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 操作名称的默认前缀更改为此处使用的前缀。
  • OTEL_PYTHON_GRPC_EXCLUDED_SERVICES：要排除的特定 gRPC 仪表的逗号分隔列表。
  • OTEL_PYTHON_ID_GENERATOR：为全局 Tracer Provider 指定要使用的 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 环境变量排除特定软件包的仪表化。环境变量可以设置为逗号分隔的软件包名称列表，以从仪表中排除。

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

最后修改 December 13, 2023: improve glossary translation (46f8201b)