feat(auto-install): Fail the build on OpenTelemetry version downgrades

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+### Features
+
+- Fail the build when OpenTelemetry is downgraded below the version the Sentry OpenTelemetry integration requires ([#1350](https://github.com/getsentry/sentry-android-gradle-plugin/pull/1350))
+  - The `sentry-opentelemetry-*` artifacts are built against specific OpenTelemetry versions. When another dependency management mechanism (most commonly Spring Boot's `io.spring.dependency-management`) forces OpenTelemetry below the version Sentry's integration requires, running against those downgraded versions can cause `ClassNotFoundException` / `NoSuchMethodError` at runtime. The new `verifySentryOpenTelemetryVersions` task detects this downgrade and fails the build early with guidance on how to fix it.
+  - You may disable this check by setting `sentry.autoInstallation.verifyOpenTelemetryVersions = false`
+
 ### Fixes
 
 - Use Sentry BOM versions for auto-installed SDK dependencies ([#1349](https://github.com/getsentry/sentry-android-gradle-plugin/pull/1349))

plugin-build/src/main/kotlin/io/sentry/android/gradle/extensions/AutoInstallExtension.kt

@@ -18,4 +18,12 @@ open class AutoInstallExtension @Inject constructor(objects: ObjectFactory) {
    */
   val sentryVersion: Property<String> =
     objects.property(String::class.java).convention(SENTRY_SDK_VERSION)
+
+  /**
+   * Whether to verify that the OpenTelemetry versions resolved on the runtime classpath satisfy
+   * what the Sentry OpenTelemetry integration requires, failing the build if any were downgraded.
+   * Defaults to `true`.
+   */
+  val verifyOpenTelemetryVersions: Property<Boolean> =
+    objects.property(Boolean::class.java).convention(true)
 }

plugin-build/src/main/kotlin/io/sentry/android/gradle/tasks/SentryOpenTelemetryVersionCheckTask.kt

@@ -0,0 +1,105 @@
+package io.sentry.android.gradle.tasks
+
+import io.sentry.android.gradle.extensions.SentryPluginExtension
+import io.sentry.android.gradle.telemetry.SentryTelemetryService
+import io.sentry.android.gradle.telemetry.withSentryTelemetry
+import org.gradle.api.DefaultTask
+import org.gradle.api.GradleException
+import org.gradle.api.Project
+import org.gradle.api.artifacts.result.ResolvedComponentResult
+import org.gradle.api.provider.Property
+import org.gradle.api.provider.Provider
+import org.gradle.api.tasks.Input
+import org.gradle.api.tasks.Internal
+import org.gradle.api.tasks.TaskAction
+import org.gradle.api.tasks.TaskProvider
+import org.gradle.work.DisableCachingByDefault
+
+/**
+ * Fails the build when the OpenTelemetry versions resolved on the runtime classpath were downgraded
+ * below what the Sentry OpenTelemetry integration requires.
+ *
+ * Sentry's `sentry-opentelemetry-*` artifacts declare the exact OpenTelemetry versions they were
+ * built and tested against. When another dependency management mechanism (most commonly
+ * `io.spring.dependency-management` / the Spring Boot BOM) forces a lower OpenTelemetry version,
+ * running against those downgraded versions can cause `ClassNotFoundException` /
+ * `NoSuchMethodError` at runtime. We detect that downgrade here and fail fast with actionable
+ * guidance instead of letting it blow up at runtime.
+ */
+@DisableCachingByDefault(because = "Only validates resolved dependency versions and has no outputs")
+abstract class SentryOpenTelemetryVersionCheckTask : DefaultTask() {
+
+  @get:Internal abstract val rootComponent: Property<ResolvedComponentResult>
+
+  @get:Input abstract val docsUrl: Property<String>
+
+  @get:Input abstract val springDependencyManagementApplied: Property<Boolean>
+
+  @get:Input abstract val hasSentryOpenTelemetryDependency: Property<Boolean>
+
+  @get:Input abstract val verifyEnabled: Property<Boolean>
+
+  init {
+    description =
+      "Checks that the resolved OpenTelemetry versions are compatible with the Sentry " +
+        "OpenTelemetry integration"
+    group = "verification"
+    // Reference task-owned properties only (not the extension/project) so the task stays
+    // configuration-cache compatible.
+    @Suppress("LeakingThis")
+    onlyIf { verifyEnabled.get() && hasSentryOpenTelemetryDependency.get() }
+  }
+
+  @TaskAction
+  fun action() {
+    val downgrades = SentryOpenTelemetryVersionChecker.collectDowngrades(rootComponent.get())
+    if (downgrades.isNotEmpty()) {
+      throw GradleException(
+        SentryOpenTelemetryVersionChecker.buildMessage(
+          downgrades,
+          docsUrl.get(),
+          springDependencyManagementApplied.get(),
+        )
+      )
+    }
+  }
+
+  companion object {
+    private const val SPRING_DEPENDENCY_MANAGEMENT_PLUGIN_ID = "io.spring.dependency-management"
+
+    fun register(
+      project: Project,
+      extension: SentryPluginExtension,
+      sentryTelemetryProvider: Provider<SentryTelemetryService>,
+      configurationName: String,
+      docsUrl: String,
+    ): TaskProvider<SentryOpenTelemetryVersionCheckTask> {
+      return project.tasks.register(
+        "verifySentryOpenTelemetryVersions",
+        SentryOpenTelemetryVersionCheckTask::class.java,
+      ) { task ->
+        val configuration = project.configurations.getByName(configurationName)
+        task.rootComponent.set(configuration.incoming.resolutionResult.rootComponent)
+        task.docsUrl.set(docsUrl)
+        // Resolved lazily (at end of configuration) so it reflects the final plugin set regardless
+        // of the order plugins are applied in the consumer's build.
+        task.springDependencyManagementApplied.set(
+          project.provider {
+            project.pluginManager.hasPlugin(SPRING_DEPENDENCY_MANAGEMENT_PLUGIN_ID)
+          }
+        )
+        // Cheap declared-dependency check (no graph resolution) so we skip entirely for the common
+        // case of projects that don't use Sentry OpenTelemetry at all.
+        task.hasSentryOpenTelemetryDependency.set(
+          project.provider {
+            configuration.allDependencies.any {
+              SentryOpenTelemetryVersionChecker.isSentryOpenTelemetryArtifact(it.group, it.name)
+            }
+          }
+        )
+        task.verifyEnabled.set(extension.autoInstallation.verifyOpenTelemetryVersions)
+        task.withSentryTelemetry(extension, sentryTelemetryProvider)
+      }
+    }
+  }
+}

plugin-build/src/main/kotlin/io/sentry/android/gradle/tasks/SentryOpenTelemetryVersionChecker.kt

@@ -0,0 +1,162 @@
+package io.sentry.android.gradle.tasks
+
+import io.sentry.android.gradle.util.SemVer
+import org.gradle.api.artifacts.ModuleVersionIdentifier
+import org.gradle.api.artifacts.component.ModuleComponentSelector
+import org.gradle.api.artifacts.result.ComponentSelectionCause
+import org.gradle.api.artifacts.result.ResolvedComponentResult
+import org.gradle.api.artifacts.result.ResolvedDependencyResult
+
+internal object SentryOpenTelemetryVersionChecker {
+  private const val SENTRY_GROUP = "io.sentry"
+  private const val SENTRY_OPENTELEMETRY_ARTIFACT_PREFIX = "sentry-opentelemetry-"
+  private const val OTEL_GROUP = "io.opentelemetry"
+
+  data class VersionDowngrade(
+    val module: String,
+    val requested: String,
+    val resolved: String,
+    val requestedBy: String,
+    val sentryBomVersion: String,
+    val reason: String?,
+  )
+
+  fun collectDowngrades(root: ResolvedComponentResult): List<VersionDowngrade> {
+    val downgrades = linkedMapOf<String, VersionDowngrade>()
+    val visited = mutableSetOf<Any>()
+    val stack = ArrayDeque<ResolvedComponentResult>()
+    stack.addLast(root)
+    while (stack.isNotEmpty()) {
+      val component = stack.removeLast()
+      if (!visited.add(component.id)) {
+        continue
+      }
+      val sentryOpenTelemetryArtifact = component.sentryOpenTelemetryArtifact()
+      for (dependency in component.dependencies) {
+        if (dependency !is ResolvedDependencyResult) {
+          continue
+        }
+        if (sentryOpenTelemetryArtifact != null) {
+          val requested = dependency.requested
+          if (requested is ModuleComponentSelector && requested.isOpenTelemetry()) {
+            val resolvedVersion = dependency.selected.moduleVersion?.version
+            if (resolvedVersion != null && isDowngrade(requested.version, resolvedVersion)) {
+              val module = "${requested.group}:${requested.module}"
+              downgrades.putIfAbsent(
+                module,
+                VersionDowngrade(
+                  module = module,
+                  requested = requested.version,
+                  resolved = resolvedVersion,
+                  requestedBy = sentryOpenTelemetryArtifact.toString(),
+                  sentryBomVersion = sentryOpenTelemetryArtifact.version,
+                  reason = dependency.selected.downgradeReason(),
+                ),
+              )
+            }
+          }
+        }
+        stack.addLast(dependency.selected)
+      }
+    }
+    return downgrades.values.toList()
+  }
+
+  fun isSentryOpenTelemetryArtifact(group: String?, name: String): Boolean =
+    group == SENTRY_GROUP && name.startsWith(SENTRY_OPENTELEMETRY_ARTIFACT_PREFIX)
+
+  fun buildMessage(
+    downgrades: List<VersionDowngrade>,
+    docsUrl: String,
+    springDependencyManagementApplied: Boolean,
+  ): String {
+    val sentryBomVersion = downgrades.first().sentryBomVersion
+    val details =
+      downgrades.joinToString(separator = "\n") { downgrade ->
+        buildString {
+          append("  - ${downgrade.module}: Sentry requires ${downgrade.requested} ")
+          append("but ${downgrade.resolved} was resolved")
+          append("\n    Requested by: ${downgrade.requestedBy}")
+          downgrade.reason?.let { append("\n    Gradle selection reason: $it") }
+        }
+      }
+    val fix =
+      if (springDependencyManagementApplied) {
+        """
+        |To fix this, import the Sentry OpenTelemetry BOM through io.spring.dependency-management so
+        |its versions win dependency resolution:
+        |
+        |  dependencyManagement {
+        |    imports {
+        |      mavenBom("io.sentry:sentry-opentelemetry-bom:$sentryBomVersion")
+        |    }
+        |  }
+        """
+          .trimMargin()
+      } else {
+        """
+        |To fix this, add the Sentry OpenTelemetry BOM as a platform dependency so its versions win
+        |dependency resolution:
+        |
+        |  dependencies {
+        |    implementation(platform("io.sentry:sentry-opentelemetry-bom:$sentryBomVersion"))
+        |  }
+        """
+          .trimMargin()
+      }
+    return """
+      |Sentry detected that OpenTelemetry was downgraded below the version its integration requires.
+      |
+      |The Sentry OpenTelemetry integration was built against specific OpenTelemetry versions,
+      |but the following were downgraded by another dependency management mechanism:
+      |
+      |$details
+      |
+      |Running with these downgraded OpenTelemetry versions can cause
+      |ClassNotFoundException / NoSuchMethodError at runtime.
+      |
+      |$fix
+      |
+      |See $docsUrl for details.
+      |
+      |You can disable this check with:
+      |
+      |  sentry {
+      |    autoInstallation.verifyOpenTelemetryVersions = false
+      |  }
+      """
+      .trimMargin()
+  }
+
+  private fun ResolvedComponentResult.sentryOpenTelemetryArtifact(): ModuleVersionIdentifier? {
+    val moduleVersion = moduleVersion ?: return null
+    if (isSentryOpenTelemetryArtifact(moduleVersion.group, moduleVersion.name)) {
+      return moduleVersion
+    }
+    return null
+  }
+
+  private fun ResolvedComponentResult.downgradeReason(): String? =
+    selectionReason.descriptions
+      .lastOrNull {
+        it.cause == ComponentSelectionCause.CONSTRAINT ||
+          it.cause == ComponentSelectionCause.FORCED ||
+          it.cause == ComponentSelectionCause.CONFLICT_RESOLUTION ||
+          it.cause == ComponentSelectionCause.SELECTED_BY_RULE
+      }
+      ?.description
+
+  private fun ModuleComponentSelector.isOpenTelemetry(): Boolean =
+    group == OTEL_GROUP || group.startsWith("$OTEL_GROUP.")
+
+  private fun isDowngrade(requested: String, resolved: String): Boolean {
+    if (requested.isBlank() || requested == resolved) {
+      return false
+    }
+    return try {
+      SemVer.parse(resolved) < SemVer.parse(requested)
+    } catch (e: IllegalArgumentException) {
+      false
+    }
+  }
+}

plugin-build/src/main/kotlin/io/sentry/android/gradle/telemetry/SentryTelemetryService.kt

@@ -315,6 +315,10 @@ abstract class SentryTelemetryService : BuildService<None>, BuildOperationListen
         "autoInstallation_sentryVersion",
         extension.autoInstallation.sentryVersion.get().toString(),
       )
+      tags.put(
+        "autoInstallation_verifyOpenTelemetryVersions",
+        extension.autoInstallation.verifyOpenTelemetryVersions.get().toString(),
+      )
       tags.put("includeDependenciesReport", extension.includeDependenciesReport.get().toString())
       tags.put("includeSourceContext", extension.includeSourceContext.get().toString())
       tags.put(

plugin-build/src/main/kotlin/io/sentry/jvm/gradle/SentryJvmPlugin.kt

@@ -8,6 +8,7 @@ import io.sentry.android.gradle.extensions.SentryPluginExtension
 import io.sentry.android.gradle.sourcecontext.OutputPaths
 import io.sentry.android.gradle.sourcecontext.SourceContext
 import io.sentry.android.gradle.tasks.SentryGenerateDebugMetaPropertiesTask
+import io.sentry.android.gradle.tasks.SentryOpenTelemetryVersionCheckTask
 import io.sentry.android.gradle.tasks.dependencies.SentryExternalDependenciesReportTaskV2
 import io.sentry.android.gradle.telemetry.SentryTelemetryService
 import io.sentry.android.gradle.util.SentryPluginUtils
@@ -130,6 +131,23 @@ constructor(private val buildEvents: BuildEventListenerRegistryInternal) : Plugi
       }
 
       project.installDependencies(extension, false)
+
+      val verifyOpenTelemetryVersionsTask =
+        SentryOpenTelemetryVersionCheckTask.register(
+          project = project,
+          extension = extension,
+          sentryTelemetryProvider = sentryTelemetryProvider,
+          configurationName = "runtimeClasspath",
+          docsUrl = OPENTELEMETRY_VERSION_MISMATCH_DOCS_URL,
+        )
+      // Gate compilation so any build that compiles, packages, runs or tests (assemble, bootJar,
+      // bootRun, check, ...) fails fast on an OpenTelemetry version mismatch.
+      project.tasks.named("classes").configure { it.dependsOn(verifyOpenTelemetryVersionsTask) }
     }
   }
+
+  companion object {
+    internal const val OPENTELEMETRY_VERSION_MISMATCH_DOCS_URL =
+      "https://docs.sentry.io/platforms/java/opentelemetry/troubleshooting/"
+  }
 }