Spring Boot 3.5 接 OpenTelemetry：尽量少写手动接入，把四个信号串起来（2026）

springboot3.5-otel/
├── hello-service/          # 编排服务 (:8080)，调用 user-service 和 greeting-service
├── user-service/           # 用户服务 (:8081)，H2 + Spring Data JDBC + Flyway
├── greeting-service/       # 多语言问候服务 (:8082)
├── shared/                 # 共享模块，包含 OTel 配置和 Logback appender
├── arch-tests/             # ArchUnit 架构规则测试
├── compose.yaml            # Grafana LGTM + 内部 otel-collector
├── grafana/                # Grafana 仪表板和自动配置
└── scripts/                # 验证脚本和 JFR 管理工具

# 1. 克隆项目
git clone https://github.com/meirongdev/springboot3.5-otel.git
cd springboot3.5-otel

# 2. 构建、启动并验证完整 demo（服务 + Collector + LGTM）
make verify-otel

# 3. 访问 Grafana 仪表板
# http://localhost:3000 （默认账号 admin/admin）

# 4. 触发一笔级联请求，观察 metrics / traces / logs
curl http://localhost:8080/api/1

// shared/build.gradle.kts
api("io.micrometer:micrometer-tracing-bridge-otel")
api("io.opentelemetry:opentelemetry-exporter-otlp")
api("io.micrometer:micrometer-registry-otlp")
api("io.opentelemetry.instrumentation:opentelemetry-logback-appender-1.0:2.13.0-alpha")
implementation("org.springframework.boot:spring-boot-starter-aop")  // for @Observed

@Component
public class OtelLogAppenderInstaller {
  @Autowired(required = false)
  private OpenTelemetry openTelemetry;

  @PostConstruct
  void install() {
    if (openTelemetry != null) {
      OpenTelemetryAppender.install(openTelemetry);
    }
  }
}

management:
  otlp:
    tracing:
      endpoint: http://localhost:4318/v1/traces
    metrics:
      export:
        url: http://localhost:4318/v1/metrics
        step: 10s
    logging:
      endpoint: http://localhost:4318/v1/logs  # ← Spring Boot 3.4+ 新增
  tracing:
    sampling:
      probability: 1.0
  observations:
    annotations:
      enabled: true
  # 通过配置定义 Resource Attributes
  opentelemetry:
    resource-attributes:
      service.name: ${spring.application.name}
      service.namespace: springboot3.5-otel
      service.version: 1.0.0
      deployment.environment: production

spring:
  threads:
    virtual:
      enabled: true

# 构建 Native Image
./gradlew nativeCompile

@Async
@Observed(name = "hello.service.getHelloAsync", contextualName = "getHelloAsync")
public CompletableFuture<HelloController.HelloResponse> getHelloAsync(Long userId, String acceptLanguage) {
    return CompletableFuture.completedFuture(getHello(userId, acceptLanguage));
}

logging:
  pattern:
    level: "%5p [${spring.application.name:},%X{traceId:-},%X{spanId:-}]"

 INFO [hello-service,4bf92f3577b34da6a3ce929d0e0e4736,00f067aa0ba902b7] HelloService : getHello called
 INFO [user-service,4bf92f3577b34da6a3ce929d0e0e4736,abc123def456789a] UserService  : getUser(1)
 INFO [greeting-service,4bf92f3577b34da6a3ce929d0e0e4736,def789abc123456b] GreetingController : GET /api/greetings

management:
  tracing:
    baggage:
      remote-fields: [x-tenant-id, x-request-id]   # W3C baggage header 传播
      correlation:
        fields: [x-tenant-id, x-request-id]         # 自动注入 MDC

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
  <include resource="org/springframework/boot/logging/logback/console-appender.xml"/>

  <appender name="OpenTelemetry"
            class="io.opentelemetry.instrumentation.logback.appender.v1_0.OpenTelemetryAppender">
    <captureExperimentalAttributes>true</captureExperimentalAttributes>
    <!-- 这里需要开启：让 SLF4J Fluent API 的 addKeyValue() 字段被捕获并作为 log attributes 转发 -->
    <captureKeyValuePairAttributes>true</captureKeyValuePairAttributes>
    <!-- 记录代码位置（类名、方法名、行号） -->
    <captureCodeAttributes>true</captureCodeAttributes>
    <captureMarkerAttribute>true</captureMarkerAttribute>
    <captureLoggerContext>true</captureLoggerContext>
  </appender>

  <!-- AsyncAppender：避免 OTel 网络 I/O 阻塞业务线程 -->
  <appender name="AsyncOpenTelemetry" class="ch.qos.logback.classic.AsyncAppender">
    <appender-ref ref="OpenTelemetry"/>
    <queueSize>8192</queueSize>
    <discardingThreshold>0</discardingThreshold>
    <maxFlushTime>1000</maxFlushTime>
    <includeCallerData>false</includeCallerData>
  </appender>

  <root level="INFO">
    <appender-ref ref="CONSOLE"/>
    <appender-ref ref="AsyncOpenTelemetry"/>
  </root>
</configuration>

services:
  hello-service:
    environment:
      # JFR Profiling — JDK 内置，零额外依赖
      - JDK_JAVA_OPTIONS=-XX:StartFlightRecording=name=production,maxsize=200m,maxage=2h,settings=profile
        -XX:MaxRAMPercentage=75 -XX:+UseG1GC -XX:MaxGCPauseMillis=200
        -Xlog:gc*:file=/logs/gc.log:time,uptime:filecount=5,filesize=10M
        -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/logs/
    volumes:
      - ./logs/hello-service:/logs

FROM eclipse-temurin:25-jre-alpine
WORKDIR /app
RUN addgroup -S app && adduser -S app -G app
RUN mkdir -p /logs && chown -R app:app /logs
COPY --from=builder /build/hello-service/build/libs/*.jar app.jar
USER app
EXPOSE 8080
# JVM 配置通过 JDK_JAVA_OPTIONS 环境变量注入（Docker Compose 管理）
ENTRYPOINT ["java", "-jar", "app.jar"]

# 使用 Make 命令管理 JFR
make jfr-check   # 查看活动录制
make jfr-dump    # 导出当前录制
make jfr-stop    # 停止录制
make jfr-analyze # 分析最新 JFR 文件
make jfr-flame   # 生成火焰图

# 或直接使用 jcmd
jcmd <pid> JFR.check
jcmd <pid> JFR.dump name=production filename=/logs/recording.jfr

spring:
  application:
    name: hello-service
  threads:
    virtual:
      enabled: true     # Java 25 Virtual Threads

server:
  port: 8080

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
  endpoint:
    health:
      show-details: always
  otlp:
    tracing:
      endpoint: http://localhost:4318/v1/traces
    metrics:
      export:
        url: http://localhost:4318/v1/metrics
        step: 10s
    logging:
      endpoint: http://localhost:4318/v1/logs   # Logs OTLP export
  tracing:
    sampling:
      probability: 1.0                          # 开发环境 100% 采样
  observations:
    annotations:
      enabled: true                             # 启用 @Observed 注解
  opentelemetry:
    resource-attributes:
      service.name: ${spring.application.name}
      service.namespace: springboot3.5-otel
      service.version: 1.0.0
      deployment.environment: production

logging:
  level:
    com.example: debug
  pattern:
    level: "%5p [${spring.application.name:},%X{traceId:-},%X{spanId:-}]"

// 本文示例里的约束：禁止手动构建 OTel SDK provider
@ArchTest
static final ArchRule noManualOtelSdkConstruction =
    noClasses()
        .should()
        .dependOnClassesThat()
        .haveFullyQualifiedName("io.opentelemetry.sdk.logs.SdkLoggerProvider")
        .orShould()
        .dependOnClassesThat()
        .haveFullyQualifiedName("io.opentelemetry.sdk.trace.SdkTracerProvider")
        .orShould()
        .dependOnClassesThat()
        .haveFullyQualifiedName("io.opentelemetry.sdk.metrics.SdkMeterProvider")
        .because("Spring Boot 3.5 auto-configures the OTel SDK");

./gradlew build
  ├─ spotlessCheck          → Google Java Format (2-space)
  ├─ Error Prone            → 编译期静态分析
  ├─ test                   → 单元 + 集成 + Pact contract testing
  ├─ jacocoTestCoverageVerification → 60% 最低覆盖率
  └─ ArchUnit               → 架构规则 + OTel 约束