1. 引言

1.1 OpenTelemetry 简介

• 可观测性标准：OpenTelemetry是 CNCF 的可观测性标准项目，提供统一的遥测数据收集和处理框架
• 多语言支持：支持Java、Go、Python、JavaScript等多种编程语言
• 厂商中立：与供应商无关的开放标准

1.2 分布式追踪的重要性

• 微服务可见性：在复杂的微服务架构中提供请求调用链路的可见性
• 性能瓶颈识别：快速定位性能瓶颈和慢查询
• 故障诊断：协助开发者快速诊断和解决分布式系统中的问题

1.3 Spring Boot 与 OpenTelemetry 集成的价值

• 自动配置：Spring Boot Starter提供开箱即用的自动配置
• 无缝集成：与Spring Boot生态系统完美集成
• 零侵入性：无需修改业务代码即可获得分布式追踪能力

2. OpenTelemetry 核心概念

2.1 基本概念

Tracing（追踪）

• Span：表示一个操作的基本单位，包含开始时间、结束时间和元数据
• Trace：表示一个完整的请求调用链路，由多个Span组成
• Context：在分布式系统中传播追踪信息的载体

Metrics（指标）

• Counter：单调递增的计数器
• Gauge：瞬时值指标
• Histogram：分布统计指标

Logging（日志）

• 结构化日志：与追踪和指标关联的结构化日志
• 关联性：日志与追踪上下文关联，便于问题定位

Context Propagation（上下文传播）

• 分布式上下文：在服务间传播追踪上下文
• 线程边界：在线程间保持追踪上下文

2.2 数据模型

Span 结构

// Span 示例Spanspan=tracer.spanBuilder("operation-name").setAttribute("http.method","GET").setAttribute("http.url","/api/users").startSpan();try{// 执行业务逻辑}finally{span.end();}

• Name：Span的名称，描述操作
• Attributes：键值对形式的元数据
• Events：时间戳标记的事件
• Links：与其他Span的关联

Trace 结构

• Trace ID：唯一标识整个追踪链路
• Parent-Child 关系：Span之间的父子关系
• 树形结构：形成完整的调用树

Attribute 和 Event

// Attributes 示例span.setAttribute("user.id",userId);span.setAttribute("request.size",requestSize);// Events 示例span.addEvent("message.received",Attributes.of(stringKey("message.id"),messageId));

3. Spring Boot Starter OpenTelemetry 概述

3.1 功能特性

自动配置机制

// application.yml 配置示例spring:application:name:user-serviceopentelemetry:endpoint:http://localhost:4317resource:attributes:service.name:${spring.application.name}traces:sampling:probability:1.0

• 零配置启动：提供合理的默认配置
• 属性覆盖：支持通过配置文件自定义配置
• 环境感知：根据运行环境自动调整配置

Spring 框架集成

• Spring MVC：自动追踪 HTTP 请求
• Spring Data：追踪数据库操作
• Spring Cloud：与服务发现、负载均衡集成

常用组件自动追踪

• RestTemplate：HTTP 客户端追踪
• WebClient：响应式 HTTP 客户端追踪
• JDBC：数据库操作追踪
• Redis：缓存操作追踪

3.2 依赖组件

OpenTelemetry SDK

• Tracer：用于创建和管理追踪
• Meter：用于创建和管理指标
• Logger：用于创建和管理日志

仪器化库

• Auto-instrumentation：自动为常用库添加追踪
• Semantic Conventions：标准化的追踪属性约定

导出器实现

• OTLP Exporter：OpenTelemetry Protocol 导出器
• Jaeger Exporter：Jaeger 追踪系统导出器
• Zipkin Exporter：Zipkin 追踪系统导出器

4. 集成配置与使用

4.1 依赖引入

Maven/Gradle 配置

// Maven 配置<dependency><groupId>io.opentelemetry.instrumentation</groupId><artifactId>opentelemetry-spring-boot-starter</artifactId><version>2.3.0-alpha</version></dependency>// 可选：Jaeger 导出器<dependency><groupId>io.opentelemetry.instrumentation</groupId><artifactId>opentelemetry-exporter-jaeger</artifactId><version>2.3.0-alpha</version></dependency>

// Gradle 配置 dependencies { implementation 'io.opentelemetry.instrumentation:opentelemetry-spring-boot-starter:2.3.0-alpha' implementation 'io.opentelemetry.instrumentation:opentelemetry-exporter-jaeger:2.3.0-alpha' }

版本兼容性说明

• Spring Boot 2.x：支持 Spring Boot 2.7+
• Spring Boot 3.x：支持 Spring Boot 3.0+
• Java 版本：支持 Java 8+

4.2 基础配置

自动配置属性

// application.yml 基础配置management:tracing:sampling:probability:1.0 // 采样概率，1.0 表示全部采样endpoints:web:exposure:include:health,info,traces,metrics // 暴露追踪端点 // OpenTelemetry 配置opentelemetry:endpoint:http://localhost:4317 // OTLP gRPC 端点protocol:grpc // 使用 gRPC 协议resource:attributes:service.name:user-service // 服务名称deployment.environment:production // 环境标识

服务名称设置

// 通过配置文件设置spring.application.name=user-service// 或通过代码设置@ConfigurationpublicclassOpenTelemetryConfig{@BeanpublicResourceotelResource(){returnResource.builder().put(ResourceAttributes.SERVICE_NAME,"user-service").put(ResourceAttributes.DEPLOYMENT_ENVIRONMENT,"production").build();}}

导出器配置

// Jaeger 导出器配置opentelemetry:exporter:jaeger:endpoint:http://localhost:14250 // Jaeger gRPC 端点timeout:30s // Zipkin 导出器配置opentelemetry:exporter:zipkin:endpoint:http://localhost:9411/api/v2/spans

4.3 高级配置选项

采样策略配置

@ConfigurationpublicclassTracingConfig{@BeanpublicSamplercustomSampler(){// 自定义采样策略returnSampler.parentBased(Sampler.traceIdRatioBased(0.1)// 10% 的请求会被采样);}}

资源属性设置

// 自定义资源属性opentelemetry:resource:attributes:service.name:user-serviceservice.version:1.0.0host.name:${HOSTNAME}cloud.region:us-east-1k8s.namespace:production

自定义标签配置

@ComponentpublicclassCustomTracingInterceptor{@EventListenerpublicvoidhandleRequest(HttpServletRequestrequest){Span.current().setAttribute("custom.request.path",request.getRequestURI());Span.current().setAttribute("custom.user.agent",request.getHeader("User-Agent"));}}

5. 自动追踪功能

5.1 HTTP 请求追踪

Spring MVC 集成

@RestController@RequestMapping("/api/users")publicclassUserController{@GetMapping("/{id}")publicResponseEntity<User>getUser(@PathVariableLongid){// 这个请求会自动被追踪Useruser=userService.findById(id);returnResponseEntity.ok(user);}@PostMappingpublicResponseEntity<User>createUser(@RequestBodyCreateUserRequestrequest){// 创建用户操作也会被追踪Useruser=userService.create(request);returnResponseEntity.status(HttpStatus.CREATED).body(user);}}

• 自动追踪：HTTP 请求会自动创建Span
• 属性收集：收集 HTTP 方法、URL、状态码等信息
• 上下文传播：追踪上下文通过 HTTP Headers 传播

RestTemplate 追踪

@ServicepublicclassUserService{privatefinalRestTemplaterestTemplate;publicUserService(RestTemplaterestTemplate){this.restTemplate=restTemplate;}publicOrdergetOrder(LongorderId){// RestTemplate 调用会被自动追踪Stringurl="http://order-service/api/orders/"+orderId;returnrestTemplate.getForObject(url,Order.class);}}

WebClient 追踪

@ServicepublicclassUserService{privatefinalWebClientwebClient;publicUserService(WebClient.BuilderwebClientBuilder){this.webClient=webClientBuilder.build();}publicMono<Order>getOrderAsync(LongorderId){// WebClient 调用会被自动追踪returnwebClient.get().uri("/api/orders/{id}",orderId).retrieve().bodyToMono(Order.class);}}

5.2 数据库操作追踪

JDBC 连接追踪

@RepositorypublicclassUserRepository{@AutowiredprivateJdbcTemplatejdbcTemplate;publicUserfindById(Longid){// SQL 查询会被自动追踪Stringsql="SELECT * FROM users WHERE id = ?";returnjdbcTemplate.queryForObject(sql,newUserRowMapper(),id);}publicvoidupdate(Useruser){// SQL 更新会被自动追踪Stringsql="UPDATE users SET name = ?, email = ? WHERE id = ?";jdbcTemplate.update(sql,user.getName(),user.getEmail(),user.getId());}}

Spring Data JPA 集成

@Entity@Table(name="users")publicclassUser{@Id@GeneratedValue(strategy=GenerationType.IDENTITY)privateLongid;privateStringname;privateStringemail;// getters and setters}@RepositorypublicinterfaceUserRepositoryextendsJpaRepository<User,Long>{// 所有 JPA 操作都会被自动追踪List<User>findByNameContaining(Stringname);}@ServicepublicclassUserService{@AutowiredprivateUserRepositoryuserRepository;publicUsersaveUser(Useruser){// save 操作会被追踪returnuserRepository.save(user);}publicList<User>findUsersByName(Stringname){// 查询操作会被追踪returnuserRepository.findByNameContaining(name);}}

Redis 操作追踪

@ServicepublicclassCacheService{@AutowiredprivateRedisTemplate<String,Object>redisTemplate;publicvoidsetCache(Stringkey,Objectvalue,Durationttl){// Redis 操作会被自动追踪redisTemplate.opsForValue().set(key,value,ttl);}publicObjectgetCache(Stringkey){// Redis 读取操作会被追踪returnredisTemplate.opsForValue().get(key);}}

5.3 消息队列追踪

Spring Kafka 集成

@ComponentpublicclassMessageProcessor{@KafkaListener(topics="user-events")publicvoidprocessUserEvent(ConsumerRecord<String,String>record){// Kafka 消息处理会被追踪Stringmessage=record.value();// 处理消息逻辑log.info("Processing user event: {}",message);}}@ServicepublicclassEventPublisher{@AutowiredprivateKafkaTemplate<String,String>kafkaTemplate;publicvoidpublishUserEvent(StringeventType,StringeventData){// Kafka 消息发送会被追踪kafkaTemplate.send("user-events",eventType,eventData);}}

RabbitMQ 追踪

@ComponentpublicclassMessageHandler{@RabbitListener(queues="user.queue")publicvoidhandleUserMessage(Stringmessage){// RabbitMQ 消息处理会被追踪log.info("Received user message: {}",message);// 处理消息逻辑}}@ServicepublicclassMessagePublisher{@AutowiredprivateRabbitTemplaterabbitTemplate;publicvoidsendUserMessage(Stringmessage){