开箱即用的插桩

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

框架	特性	默认值
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	启用数据库语句的清洗处理。

Feedback

Was this page helpful?

Thank you. Your feedback is appreciated!

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

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