SpringBoot Gradle集成OpenTelemetry遇ClassNotFoundException错误

数据老陈

2026-6-13

问题

我有一个基于Java 17、SpringBoot 3.3.4和Gradle的应用，尝试添加OpenTelemetry Instrumentation依赖后，执行命令./gradlew composedown clean cleandocker assemble dockerbuild composeup时，出现错误：

java.lang.ClassNotFoundException: io.opentelemetry.api.incubator.events.EventLoggerProvider

我的libs.versions.toml文件内容：

# Once you will upgrade spring boot version all those dependencies will be updated accordingly
[versions]
flagsmithStarterVersion = "0.2.69"
featureFlagsJavaClientVersion = "0.3.85"
common-platform = "6.0.563"
webjars-bootsrap = "5.3.3"
springdoc-openapi = "2.6.0"
login-filter = "50.243"
logback-encoder = "8.0"
guava = "33.3.1-jre"
kjobster = "2.7.160"
jaxb = "2.3.1"
mysql-connector = "8.0.33"
jooq-codegen = "3.19.11"
aws-sdk-version = "2.30.13"
javaxAnnotation = "1.3.2"

[libraries]
spring-context = { module = "org.springframework:spring-context" }
spring-boot-kafka = { module = "org.springframework.kafka:spring-kafka"}
spring-boot-starter-jdbc = { module = "org.springframework.boot:spring-boot-starter-jdbc" }
spring-boot-starter-data-jdbc = { module = "org.springframework.boot:spring-boot-starter-data-jdbc" }
spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web" }
spring-boot-starter-jooq = { module = "org.springframework.boot:spring-boot-starter-jooq" }
jooq-codegen = { module = "org.jooq:jooq-codegen", version.ref="jooq-codegen" }
spring-boot-starter-thymeleaf = { module = "org.springframework.boot:spring-boot-starter-thymeleaf" }
spring-boot-starter-security = { module = "org.springframework.boot:spring-boot-starter-security" }
spring-boot-starter-actuator = { module = "org.springframework.boot:spring-boot-starter-actuator" }
spring-boot-devtools = { module = "org.springframework.boot:spring-boot-devtools" }
spring-boot-configuration-processor = { module = "org.springframework.boot:spring-boot-configuration-processor" }
spring-aspects = { module = "org.springframework:spring-aspects" }
liquibase = { module = "org.liquibase:liquibase-core" }
commons-pool2 = { module = "org.apache.commons:commons-pool2" }
commons-lang3 = { module = "org.apache.commons:commons-lang3" }
micrometer-registry-statsd = { module = "io.micrometer:micrometer-registry-statsd" }
datadog-utils = { module = "com.kenshoo:datadog-utils", version.ref = "common-platform" }
aws-credentials-provider = { module = "com.kenshoo:aws-credentials-provider", version.ref = "common-platform" }
webjars-bootstrap = { module = "org.webjars:bootstrap", version.ref = "webjars-bootsrap" }
springdoc-openapi-starter = { module = "org.springdoc:springdoc-openapi-starter-webmvc-ui", version.ref = "springdoc-openapi" }
kenshoo-ssofilter-spring = { module = "com.kenshoo.ls:ssofilter-spring", version.ref = "login-filter" }
logback-encoder = { module = "net.logstash.logback:logstash-logback-encoder", version.ref = "logback-encoder" }
guava = { module = "com.google.guava:guava", version.ref = "guava" }
kjobster = { module = "com.kenshoo:kjobster", version.ref = "kjobster" }
dropwizard-metrics-core = { module = "io.dropwizard.metrics:metrics-core" }
jaxb-api = { module = "javax.xml.bind:jaxb-api", version.ref = "jaxb" }
jaxb-runtime = { module = "org.glassfish.jaxb:jaxb-runtime", version.ref = "jaxb" }
lombok = { module = "org.projectlombok:lombok" }
mysql-connector-java = { module = "mysql:mysql-connector-java", version.ref="mysql-connector" }

awsBedrockAgent = { module = "software.amazon.awssdk:bedrockagent", version.ref = "aws-sdk-version" }
awsBedrockAgentRuntime = { module = "software.amazon.awssdk:bedrockagentruntime", version.ref = "aws-sdk-version" }
awsBedrockRuntime = { module = "software.amazon.awssdk:bedrockruntime", version.ref = "aws-sdk-version" }
awsNettyNioClient = { module = "software.amazon.awssdk:netty-nio-client", version.ref = "aws-sdk-version" }
awsSts = { module = "software.amazon.awssdk:sts",  version.ref = "aws-sdk-version" }
awsSdkS3 = { group = "software.amazon.awssdk", name = "s3", version.ref = "aws-sdk-version" }
awsSdkS3TransferManager = { group = "software.amazon.awssdk", name = "s3-transfer-manager", version.ref = "aws-sdk-version" }

reportApiEntities = { module = "com.kenshoo:flat-view-public-api-entities", version = "latest.integration" }
flatViewCommon = { module = "com.kenshoo:flat-view-common", version = "latest.integration" }

openPlatformApiModel = { module = "com.kenshoo:open-platform", version = "5.1.427" }
jacksonDatabind = { module = "com.fasterxml.jackson.core:jackson-databind", version = "2.15.0" }
springWeb = { module = "org.springframework:spring-web"}
springRetry = { module = "org.springframework.retry:spring-retry", version = "2.0.10" }
jakartaAnnotation = { module = "jakarta.annotation:jakarta.annotation-api", version = "3.0.0" }
jwt-decoder = { module = "com.auth0:java-jwt", version = "4.4.0" }
javaxAnnotation = { group = "javax.annotation", name = "javax.annotation-api", version.ref = "javaxAnnotation" }
javaCsv = { module = "net.sourceforge.javacsv:javacsv", version = "2.0" }
flagsmithStarter = { module = "io.skai.feature.flag:feature-flags-spring-boot-starter", version.ref = "flagsmithStarterVersion"}
featureFlagsJavaClient = { module = "io.skai.feature.flag:feature-flags-java-client", version.ref = "featureFlagsJavaClientVersion"}

otelSpringBootStarted = {module = "io.opentelemetry.instrumentation:opentelemetry-spring-boot-starter"}
otelIncubator = {module = "io.opentelemetry:opentelemetry-api-incubator", version = "1.48.0-alpha"}

主build.gradle文件内容：

apply plugin: 'docker-compose'
...
buildscript {
    ext {
        springBootVersion = '3.3.4'
        springCloudVersion = '2023.0.3'
        dependencyManagementPluginVersion = '1.1.6'
        dockerComposePluginVersion = '0.17.8'
        gradleTasksPluginVersion = '0.1.29'
        vaultkaPluginVersion = '0.2.39'
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
        classpath("io.spring.gradle:dependency-management-plugin:${dependencyManagementPluginVersion}")
        classpath "com.avast.gradle:gradle-docker-compose-plugin:${dockerComposePluginVersion}"
        classpath "com.kenshoo.tasksplugin:gradle-tasks-plugin:${gradleTasksPluginVersion}"
        classpath "com.kenshoo.vaultkaplugin:vaultka-gradle-plugin:${vaultkaPluginVersion}"
        classpath "org.sonarsource.scanner.gradle:sonarqube-gradle-plugin:5.1.0.4882"
    }
    configurations.classpath {
        resolutionStrategy.activateDependencyLocking()
    }
...
dependencies {
    implementation project(path: ':my-module')
}
...
subprojects {
    apply plugin: 'java'
    apply plugin: 'idea'
    apply plugin: 'io.spring.dependency-management'

   ...

    java {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
...
dependencyManagement {
        imports {
            mavenBom "org.springframework.boot:spring-boot-dependencies:${springBootVersion}"
            mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
            mavenBom "io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom:2.14.0"
        }
    }

my-module/build.gradle文件内容：

plugins {
    id 'java'
}
repositories {
    mavenCentral()
}

dependencies {
    compileOnly libs.lombok
    annotationProcessor libs.lombok

    implementation libs.featureFlagsJavaClient
    implementation libs.awsSdkS3
    implementation libs.awsSdkS3TransferManager
    implementation libs.awsBedrockAgent
    implementation libs.awsBedrockAgentRuntime
    implementation libs.awsBedrockRuntime
    implementation libs.awsNettyNioClient
    implementation libs.awsSts
    implementation dependencies.create(libs.aws.credentials.provider.get()) {
        exclude group: 'org.apache.commons', module: 'commons-lang'
    }
    implementation libs.spring.context
    implementation libs.jacksonDatabind
    implementation libs.springWeb
    implementation libs.springRetry
    implementation libs.jakartaAnnotation
    implementation libs.micrometer.registry.statsd

    implementation libs.otelSpringBootStarted
    implementation libs.otelIncubator

    implementation project(path: ':chat-executor-api')
    testImplementation platform('org.junit:junit-bom:5.9.1')
    testImplementation 'org.junit.jupiter:junit-jupiter'
}

我尝试过降低opentelemetry-spring-boot-starter和opentelemetry-api-incubator的版本，或者移除opentelemetry-api-incubator依赖，但都没有解决问题。检查依赖树时可以看到io.opentelemetry:opentelemetry-api-incubator:1.48.0-alpha已存在。

解决办法

问题根源

你遇到的ClassNotFoundException是因为OpenTelemetry组件版本不匹配：

主build.gradle中引入的opentelemetry-instrumentation-bom:2.14.0会统一管理所有OpenTelemetry相关依赖的版本，包括opentelemetry-spring-boot-starter。
但你在libs.versions.toml中手动指定了otelIncubator的版本为1.48.0-alpha，这个版本和BOM管理的版本不兼容，导致运行时找不到对应类。

具体修复步骤

统一依赖版本，移除手动指定的incubator版本
修改libs.versions.toml中的otelIncubator配置，去掉手动指定的版本，让它继承BOM的版本：

otelIncubator = {module = "io.opentelemetry:opentelemetry-api-incubator"}

验证依赖版本一致性
执行以下命令查看opentelemetry-api-incubator的实际依赖版本，确认它和BOM版本配套：

./gradlew :my-module:dependencies --configuration runtimeClasspath | grep opentelemetry-api-incubator

正常情况下，版本应该和BOM对应的API版本一致（比如1.48.0，不带-alpha，因为BOM会管理稳定版本）。

重新构建并运行
执行你的构建命令：

./gradlew composedown clean cleandocker assemble dockerbuild composeup

额外排查点

如果上述步骤无效，检查以下内容：

确认my-module/build.gradle中otelIncubator是implementation依赖，而非compileOnly，确保它被打包到运行时环境中。
检查是否有其他第三方依赖引入了冲突版本的OpenTelemetry组件，可以用以下命令查看依赖来源，排除冲突版本：

./gradlew dependencyInsight --dependency io.opentelemetry:opentelemetry-api-incubator --configuration runtimeClasspath

内容的提问来源于stack exchange，提问作者Chedva

SpringBoot Gradle集成OpenTelemetry遇ClassNotFoundException错误

问题根源 #

具体修复步骤 #

额外排查点 #

问题根源

具体修复步骤

额外排查点