开箱即用的插桩

多种框架都提供开箱即用的插桩功能：

框架	特性	默认值
JDBC	`otel.instrumentation.jdbc.enabled`	true
Logback	`otel.instrumentation.logback-appender.enabled`	true
Logback MDC	`otel.instrumentation.logback-mdc.enabled`	true
Spring Web	`otel.instrumentation.spring-web.enabled`	true
Spring Web MVC	`otel.instrumentation.spring-webmvc.enabled`	true
Spring WebFlux	`otel.instrumentation.spring-webflux.enabled`	true
Kafka	`otel.instrumentation.kafka.enabled`	true
MongoDB	`otel.instrumentation.mongo.enabled`	true
Micrometer	`otel.instrumentation.micrometer.enabled`	false
R2DBC (reactive JDBC)	`otel.instrumentation.r2dbc.enabled`	true

选择性的打开插桩

要仅使用特定的插桩，首先通过将 otel.instrumentation.common.default-enabled 属性设置为 false 来关闭所有插桩。然后，逐个启用插桩。

例如，如果你只想启用 JDBC 插桩，请将 otel.instrumentation.jdbc.enabled 设置为 true。

通用插桩配置

所有数据库插桩的通用属性：

系统特性	类型	默认值	描述
`otel.instrumentation.common.db-statement-sanitizer.enabled`	Boolean	true	启用数据库语句的清理。

JDBC 插桩

系统特性	类型	默认值	描述
`otel.instrumentation.jdbc.statement-sanitizer.enabled`	Boolean	true	启用数据库语句的清理。

Logback

你可以使用系统特性启用实验性功能以捕获属性：

系统特性	类型	默认值	描述
`otel.instrumentation.logback-appender.experimental-log-attributes`	Boolean	false	启用实验性日志属性 `thread.name` 和 `thread.id` 的捕获。
`otel.instrumentation.logback-appender.experimental.capture-code-attributes`	Boolean	false	启用源代码属性的捕获。请注意，在日志记录位置捕获源代码属性可能会增加性能开销。
`otel.instrumentation.logback-appender.experimental.capture-marker-attribute`	Boolean	false	启用将 Logback 标记作为属性捕获。
`otel.instrumentation.logback-appender.experimental.capture-key-value-pair-attributes`	Boolean	false	启用将 Logback 键值对作为属性捕获。
`otel.instrumentation.logback-appender.experimental.capture-logger-context-attributes`	Boolean	false	启用将 Logback 日志上下文属性作为属性捕获。
`otel.instrumentation.logback-appender.experimental.capture-mdc-attributes`	String		以逗号分隔的要捕获的 MDC 属性列表。使用通配符 `*` 可捕获所有属性。

或者，你可以通过在 logback.xml 或 logback-spring.xml 文件中添加 OpenTelemetry Logback appender 来启用这些功能：

<?xml version="1.0" encoding="UTF-8"?> <configuration>  <appender name="console" class="ch.qos.logback.core.ConsoleAppender">  <encoder>  <pattern>  %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n  </pattern>  </encoder>  </appender>  <appender name="OpenTelemetry"  class="io.opentelemetry.instrumentation.logback.appender.v1_0.OpenTelemetryAppender">  <captureExperimentalAttributes>false</captureExperimentalAttributes>  <captureCodeAttributes>true</captureCodeAttributes>  <captureMarkerAttribute>true</captureMarkerAttribute>  <captureKeyValuePairAttributes>true</captureKeyValuePairAttributes>  <captureLoggerContext>true</captureLoggerContext>  <captureMdcAttributes>*</captureMdcAttributes>  </appender>  <root level="INFO">  <appender-ref ref="console"/>  <appender-ref ref="OpenTelemetry"/>  </root> </configuration>

Spring Web 自动配置

为 opentelemetry-spring-web-3.1 中定义的 RestTemplate 跟踪拦截器提供自动配置。此自动配置通过应用 RestTemplate Bean 后置处理器，对所有使用 Spring RestTemplate Bean 发送的请求进行插桩。此功能支持 spring web 版本 3.1+。要了解有关 OpenTelemetry RestTemplate 拦截器的更多信息，请参见 opentelemetry-spring-web-3.1。

支持以下几种创建 RestTemplate 的方式：

package otel;  import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.client.RestTemplate;  @Configuration public class RestTemplateConfig {   @Bean  public RestTemplate restTemplate() {  return new RestTemplate();  } }

package otel;  import org.springframework.boot.web.client.RestTemplateBuilder; import org.springframework.web.bind.annotation.RestController; import org.springframework.web.client.RestTemplate;  @RestController public class RestTemplateController {   private final RestTemplate restTemplate;   public RestTemplateController(RestTemplateBuilder restTemplateBuilder) {  restTemplate = restTemplateBuilder.rootUri("http://localhost:8080").build();  } }

支持以下几种创建 RestClient 的方式：

package otel;  import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.client.RestClient;  @Configuration public class RestClientConfig {   @Bean  public RestClient restClient() {  return RestClient.create();  } }

package otel;  import org.springframework.web.bind.annotation.RestController; import org.springframework.web.client.RestClient;  @RestController public class RestClientController {   private final RestClient restClient;   public RestClientController(RestClient.Builder restClientBuilder) {  restClient = restClientBuilder.baseUrl("http://localhost:8080").build();  } }

正如使用 Java 代理一样，你可以配置捕获以下实体：

Spring Web MVC 自动配置

此功能通过向应用程序上下文添加一个生成遥测数据的 Servlet Filter Bean，为 Spring WebMVC 控制器自动配置插桩。该过滤器使用服务器 Span 装饰请求执行，如果在 HTTP 请求中接收到传入的跟踪上下文，则会传播该上下文。要了解更多关于 OpenTelemetry Spring WebMVC 插桩的信息，请参阅 opentelemetry-spring-webmvc-5.3 插桩库。

正如使用 Java 代理一样，你可以配置捕获以下实体：

Spring WebFlux 自动配置

为 opentelemetry-spring-webflux-5.3 提供自动配置。此自动配置通过应用 Bean 后置处理器，对所有使用 Spring 的 WebClient 和 WebClient Builder Bean 发送的出站 HTTP 请求进行插桩。此功能支持 Spring WebFlux 版本 5.0+。有关详细信息，请参阅 opentelemetry-spring-webflux-5.3。

以下是创建 WebClient 的支持方式：

package otel;  import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.reactive.function.client.WebClient;  @Configuration public class WebClientConfig {   @Bean  public WebClient webClient() {  return WebClient.create();  } }

package otel;  import org.springframework.web.bind.annotation.RestController; import org.springframework.web.reactive.function.client.WebClient;  @RestController public class WebClientController {   private final WebClient webClient;   public WebClientController(WebClient.Builder webClientBuilder) {  webClient = webClientBuilder.baseUrl("http://localhost:8080").build();  } }

Kafka 插桩

为 Kafka 客户端插桩提供自动配置。

系统特性	类型	默认值	描述
`otel.instrumentation.kafka.experimental-span-attributes`	Boolean	false	启用实验性跨度属性的捕获。

Micrometer 插桩

为 Micrometer 到 OpenTelemetry 的桥接提供自动配置。

MongoDB 插桩

为 MongoDB 客户端插桩提供自动配置。

系统特性	类型	默认值	描述
`otel.instrumentation.mongo.statement-sanitizer.enabled`	Boolean	true	启用数据库语句的清洗处理。

R2DBC 插桩

为 OpenTelemetry R2DBC 插桩提供自动配置。

系统特性	类型	默认值	描述
`otel.instrumentation.r2dbc.statement-sanitizer.enabled`	Boolean	true	启用数据库语句的清洗处理。

意见反馈

这个页面对您有帮助吗？

Thank you. Your feedback is appreciated!

Please let us know how we can improve this page. Your feedback is appreciated!

最后修改 October 15, 2025: [zh] Update and add content/zh/docs/zero-code/java/*.md (#7961) (07bffdb4)