Agent配置

SDK自动配置

SDK的自动配置模块用于代理的基本配置。阅读 文档 以查找如配置导出或采样等设置。

以下是一些指向特定部分的SDK和代理的配置选项的快速链接：

• 导出器
  • OTLP导出器（跨度、指标和日志导出器）
  • Jaeger导出器
  • Zipkin导出器
  • Prometheus导出器
  • 日志导出器
• 追踪上下文传播
• OpenTelemetry资源和服务名称
• 批处理跨度处理器
• 采样器
• 跨度限制
• 使用SPI进一步配置SDK

配置代理

代理可以从以下一个或多个来源获取配置（按优先级排序）：

• 系统属性
• 环境变量
• 配置文件
• 通过 AutoConfigurationCustomizer#addPropertiesSupplier() 函数提供的属性；使用 AutoConfigurationCustomizerProvider SPI

使用环境变量进行配置

在某些环境中，使用环境变量进行配置更加优先。任何可通过系统属性进行配置的设置也可以通过环境变量进行配置。下面的设置选项中许多都包括了两种选项，但当它们不适用时，请按照以下步骤确定所需系统属性的正确名称映射：

• 将系统属性转换为大写。
• 用下划线（_）替换所有的 . 和 - 字符。

例如，otel.instrumentation.common.default-enabled 将转换为 OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED。

配置文件

可以通过设置以下属性来提供代理配置文件的路径：

扩展

可以通过设置以下属性来启用扩展：

Java代理日志输出

可以通过设置以下属性来配置Java代理的日志输出：

通用仪表配置

适用于多个仪表的通用设置。

同级服务名称

同级服务名称 是建立连接的远程服务的名称。它对应于本地服务的资源中的service.name属性。

1.2.3.4=cats-service,dogs-abcdef123.serverlessapis.com=dogs-api

1.2.3.4:443=cats-service,dogs-abcdef123.serverlessapis.com:80/api=dogs-api

数据库语句脱敏

代理在设置db.statement语义属性之前，会对所有的数据库查询/语句进行脱敏。查询字符串中的所有值（字符串、数字）都将替换为问号（?）。

注意：JDBC绑定参数不会被捕获在db.statement中。如果您想捕获绑定参数，请参阅 相关问题。

例子：

• SQL查询语句SELECT a from b where password="secret"在导出的跨度中将显示为SELECT a from b where password=?；
• Redis命令HSET map password "secret"在导出的跨度中将显示为HSET map password ?。

默认情况下，这个行为对所有的数据库仪表都是开启的。使用以下属性来禁用它：

捕获HTTP请求和响应头

您可以配置代理根据 语义约定 捕获预定义的HTTP头作为跨度属性。使用以下属性定义要捕获的HTTP头：

所有HTTP客户端和服务器仪表支持这些配置选项。

注意：表中列出的属性/环境变量名称仍处于实验阶段，因此可能会发生更改。

捕获Servlet请求参数

您可以配置代理，以捕获由Servlet API处理的请求的预定义HTTP请求参数作为跨度属性。使用以下属性定义要捕获的Servlet请求参数：

注意：表中列出的属性/环境变量名称仍处于实验阶段，因此可能会发生更改。

捕获消息中间件仪表中的消费者消息接收遥测

您可以配置代理以捕获消息中间件的消费者消息接收遥测。使用以下属性启用它：

请注意，这将导致消费者端启动一个新的跟踪，只有一个跨度链接将其与生产者跟踪连接。

注意：表中列出的属性/环境变量名称仍处于实验阶段，因此可能会发生更改。

禁止特定的自动仪表

完全禁用代理

您可以使用 -Dotel.javaagent.enabled=false（或等效的环境变量OTEL_JAVAAGENT_ENABLED=false）禁用代理。

仅启用特定的仪表

您可以禁用所有默认的自动仪表，然后选择性地重新启用每个仪表。这样做可以减少启动开销或更好地控制应用的仪表应用。

• 使用 -Dotel.instrumentation.common.default-enabled=false（或等价的环境变量OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED=false）禁用代理中的所有仪表。
• 使用 -Dotel.instrumentation.[name].enabled=true（或等价的环境变量OTEL_INSTRUMENTATION_[NAME]_ENABLED）逐个启用每个所需的仪表。这里的 [name]（[NAME]）是以下相应仪表的名称。

注意：某些仪表依赖于其他仪表的正常运行。当选择性启用仪表时，确保同时启用其传递依赖项。确定这种依赖关系的关系留给用户自行决定。

仅启用手动仪表

可以抑制所有自动仪表的启用，但支持使用 @WithSpan 和正常API交互的手动仪表，使用 -Dotel.instrumentation.common.default-enabled=false -Dotel.instrumentation.opentelemetry-api.enabled=true -Dotel.instrumentation.opentelemetry-instrumentation-annotations.enabled=true。

抑制特定的代理仪表

可以使用 -Dotel.instrumentation.[name].enabled=false（或等效的环境变量OTEL_INSTRUMENTATION_[NAME]_ENABLED）来抑制对特定库的代理仪表。这里的name（NAME）是相应的仪表name：

注意：使用环境变量时，破折号（-）应转换为下划线（_）。例如，要禁止akka-actor库的跟踪，请将OTEL_INSTRUMENTATION_AKKA_ACTOR_ENABLED设置为false。

抑制控制器和/或视图跨度

某些仪表（例如，Spring Web MVC 仪表）生成 SpanKind.Internal 跨度以捕获控制器和/或视图的执行。可以使用以下配置设置来抑制这些跨度，而无需禁用整个仪表，这样也可以禁用仪表在父 SpanKind.Server 跨度上捕获 http.route 和相关的跨度名称。

仪表跨度抑制行为

由于代理中仪表的一些库还使用了低层级的被仪表化的库，这在结果上会产生重复的遥测数据。例如：

• 由 Reactor Netty HTTP client 仪表产生的跨度也会有由 Netty 仪表产生的重复的 HTTP client 跨度；
• 由 AWS SDK 仪表产生的 Dynamo DB 跨度会有由其内部的 HTTP client 库（也被仪表化）产生的子 HTTP client 跨度；
• 由 Tomcat 仪表产生的跨度会有由通用 Servlet API 仪表产生的重复的 HTTP server 跨度。

Java代理通过检测和抑制重复遥测数据的嵌套跨度来防止这些情况。抑制行为可以使用以下配置选项进行配置：

例如，假设我们仪表化了一个内部使用 Reactor Netty HTTP 客户端的数据库客户端：

使用默认的 semconv 抑制策略，会产生2个嵌套的 CLIENT 跨度：

• 由数据库客户端仪表产生并具有数据库客户端语义属性的 CLIENT 跨度；
• 由 Reactor Netty 仪表产生并具有 HTTP 客户端语义属性的 CLIENT 跨度。

Netty 仪表化将被抑制，因为其重复了 Reactor Netty 仪表化。

使用抑制策略 span-kind，只会产生一个跨度：

• 由数据库客户端仪表产生并具有数据库客户端语义属性的 CLIENT 跨度。

Reactor Netty 和 Netty 仪表化都将被抑制，因为它们均生成了 CLIENT 跨度。

最后，使用抑制策略 none，将产生3个跨度：

• 由数据库客户端仪表产生并具有数据库客户端语义属性的 CLIENT 跨度；
• 由 Reactor Netty 仪表产生并具有 HTTP 客户端语义属性的 CLIENT 跨度；
• 由 Netty 仪表产生并具有 HTTP 客户端语义属性的 CLIENT 跨度。