chore(android-sqlite): Skip wrapping SupportSQLiteDriver bridge to avoid duplicate spans

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## Unreleased
+
+### Features
+
+- Add `SentrySQLiteDriver` to `sentry-android-sqlite` for instrumenting AndroidX's `SQLiteDriver` ([#5466](https://github.com/getsentry/sentry-java/pull/5466))
+  - Automatically generates spans for all SQLite statements
+  - To use it, pass your `SQLiteDriver` to `SentrySQLiteDriver.create(...)`
+  - You'll need `androidx.sqlite:sqlite` (2.5.0+) on your app's classpath (Room usually provides it for you). androidx.sqlite 2.6.0+ requires minSdk 23.
+  - The Room 2.7+ `androidx.sqlite.driver.SupportSQLiteDriver` bridge adapter is recognized and skipped by `SentrySQLiteDriver.create(...)` so apps that wrap both the open helper and the bridge driver do not emit duplicate spans. Spans come from the open helper layer in that configuration.
+  - See https://docs.sentry.io/platforms/android/integrations/room-and-sqlite/ for more details, including info about migrating from `SentrySupportSQLiteOpenHelper`
+
 ## 8.43.1
 
 ### Fixes

gradle/libs.versions.toml

@@ -5,42 +5,49 @@ androidxNavigation = "2.4.2"
 androidxTestCore = "1.7.0"
 androidxCompose = "1.6.3"
 asyncProfiler = "4.2"
+camerax = "1.4.0"
 composeCompiler = "1.5.14"
 coroutines = "1.6.1"
 espresso = "3.7.0"
 feign = "11.6"
+gummyBears = "0.12.0"
 jacoco = "0.8.7"
 jackson = "2.18.3"
 jetbrainsCompose = "1.6.11"
 kotlin = "2.2.0"
 kotlinSpring7 = "2.2.0"
 kotlin-compatible-version = "1.9"
+ksp = "2.2.0-2.0.2"
 ktorClient = "3.0.0"
 logback = "1.2.9"
 log4j2 = "2.20.0"
 nopen = "1.0.1"
 # see https://www.jetbrains.com/help/kotlin-multiplatform-dev/compose-compatibility-and-versioning.html#kotlin-compatibility
 # see https://developer.android.com/jetpack/androidx/releases/compose-kotlin
 okhttp = "4.9.2"
+openfeature = "1.18.2"
 otel = "1.60.1"
 otelInstrumentation = "2.26.0"
 otelInstrumentationAlpha = "2.26.0-alpha"
 # check https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/dependencyManagement/build.gradle.kts#L49 for release version above to find a compatible version
 otelSemanticConventions = "1.40.0"
 otelSemanticConventionsAlpha = "1.40.0-alpha"
 retrofit = "2.9.0"
+room2 = "2.8.4"
+room3 = "3.0.0-alpha06"
+sqlite = "2.6.2"
+sqliteAlpha = "2.7.0-alpha06" # Required by Room3 3.0.0-alpha*
 slf4j = "1.7.30"
+spotless = "8.4.0"
 springboot2 = "2.7.18"
 springboot3 = "3.5.0"
 springboot4 = "4.0.0"
+sqldelight = "2.3.2"
+
 # Android
 targetSdk = "36"
 compileSdk = "36"
 minSdk = "21"
-spotless = "8.4.0"
-gummyBears = "0.12.0"
-camerax = "1.4.0"
-openfeature = "1.18.2"
 
 [plugins]
 kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
@@ -50,6 +57,7 @@ kotlin-jvm-spring7 = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlinSpr
 kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
 kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
 kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
+ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
 buildconfig = { id = "com.github.gmazzo.buildconfig", version = "5.6.5" }
 dokka = { id = "org.jetbrains.dokka", version = "2.0.0" }
 dokka-javadoc = { id = "org.jetbrains.dokka-javadoc", version = "2.0.0" }
@@ -64,6 +72,7 @@ vanniktech-maven-publish = { id = "com.vanniktech.maven.publish", version = "0.3
 springboot3 = { id = "org.springframework.boot", version.ref = "springboot3" }
 springboot4 = { id = "org.springframework.boot", version.ref = "springboot4" }
 spring-dependency-management = { id = "io.spring.dependency-management", version = "1.1.7" }
+sqldelight = { id = "app.cash.sqldelight", version.ref = "sqldelight" }
 gretty = { id = "org.gretty", version = "4.0.0" }
 animalsniffer = { id = "ru.vyarus.animalsniffer", version = "2.0.1" }
 sentry = { id = "io.sentry.android.gradle", version = "6.6.0"}
@@ -94,7 +103,14 @@ androidx-lifecycle-common-java8 = { module = "androidx.lifecycle:lifecycle-commo
 androidx-lifecycle-process = { module = "androidx.lifecycle:lifecycle-process", version.ref = "androidxLifecycle" }
 androidx-navigation-runtime = { module = "androidx.navigation:navigation-runtime", version.ref = "androidxNavigation" }
 androidx-navigation-compose = { module = "androidx.navigation:navigation-compose", version.ref = "androidxNavigation" }
-androidx-sqlite = { module = "androidx.sqlite:sqlite", version = "2.5.2" }
+androidx-room-compiler = { module = "androidx.room:room-compiler", version.ref = "room2" }
+androidx-room-ktx = { module = "androidx.room:room-ktx", version.ref = "room2" }
+androidx-room-runtime = { module = "androidx.room:room-runtime", version.ref = "room2" }
+androidx-room3-compiler = { module = "androidx.room3:room3-compiler", version.ref = "room3" }
+androidx-room3-runtime = { module = "androidx.room3:room3-runtime", version.ref = "room3" }
+androidx-sqlite = { module = "androidx.sqlite:sqlite", version.ref = "sqlite" }
+androidx-sqlite-bundled = { module = "androidx.sqlite:sqlite-bundled", version.ref = "sqliteAlpha" }
+androidx-sqlite-framework = { module = "androidx.sqlite:sqlite-framework", version.ref = "sqliteAlpha" }
 androidx-recyclerview = { module = "androidx.recyclerview:recyclerview", version = "1.2.1" }
 androidx-browser = { module = "androidx.browser:browser", version = "1.8.0" }
 async-profiler = { module = "tools.profiler:async-profiler", version.ref = "asyncProfiler" }
@@ -207,6 +223,7 @@ springboot4-starter-jdbc = { module = "org.springframework.boot:spring-boot-star
 springboot4-starter-actuator = { module = "org.springframework.boot:spring-boot-starter-actuator", version.ref = "springboot4" }
 springboot4-starter-cache = { module = "org.springframework.boot:spring-boot-starter-cache", version.ref = "springboot4" }
 springboot4-starter-kafka = { module = "org.springframework.boot:spring-boot-starter-kafka", version.ref = "springboot4" }
+sqldelight-android-driver = { module = "app.cash.sqldelight:android-driver", version.ref = "sqldelight" }
 timber = { module = "com.jakewharton.timber:timber", version = "4.7.1" }
 
 # Animalsniffer signature
@@ -249,3 +266,7 @@ msgpack = { module = "org.msgpack:msgpack-core", version = "0.9.8" }
 okhttp-mockwebserver = { module = "com.squareup.okhttp3:mockwebserver", version.ref = "okhttp" }
 okio = { module = "com.squareup.okio:okio", version = "1.13.0" }
 roboelectric = { module = "org.robolectric:robolectric", version = "4.15" }
+
+[bundles]
+androidx-room2 = ["androidx-room-runtime", "androidx-room-ktx"]
+androidx-sqlite-drivers = ["androidx-sqlite-bundled", "androidx-sqlite-framework"]

sentry-android-sqlite/README.md

@@ -0,0 +1,21 @@
+# sentry-android-sqlite
+
+This module provides automatic SQLite query instrumentation for Android.
+
+Two instrumentation paths are supported, matching the two SQLite APIs offered by AndroidX:
+
+- **`androidx.sqlite.SQLiteDriver`** — used by Room 2.7+ via `Room.databaseBuilder(...).setDriver(...)` and by SQLDelight via its AndroidX SQLite driver.
+- **`androidx.sqlite.db.SupportSQLiteOpenHelper`** — used by legacy Room via `Room.databaseBuilder(...).openHelperFactory(...)`, or applied automatically by the Sentry Android Gradle plugin.
+
+Please consult the [Sentry Docs](https://docs.sentry.io/platforms/android/integrations/room-and-sqlite/) for usage and migration guidance, as well as how to avoid duplicate spans when using Room's `SupportSQLiteDriver` adapter.
+
+## Package layout
+
+This module is organized as two separate packages:
+
+- **`io.sentry.android.sqlite`**: Android-specific code. Classes here depend on `android.database.*` (e.g., `CrossProcessCursor`, `SQLException`) and/or on `androidx.sqlite.db.*`, the Android-only compatibility layer over the platform's SQLite. The `SentrySupportSQLiteOpenHelper` path and its `SQLiteSpanManager` wrapper live here.
+- **`io.sentry.sqlite`**: Code whose contract depends only on the multiplatform `androidx.sqlite.*` interfaces (e.g., `SQLiteDriver` and `SQLiteConnection`). `SentrySQLiteDriver` and shared span instrumentation via `SQLiteSpanInstrumentation` live here.
+
+The split anticipates the possibility of future Kotlin Multiplatform support. The `androidx.sqlite.*` driver interfaces are defined in the library's `commonMain` source set and are reused by Room across Android, JVM, and native targets. Classes in `io.sentry.sqlite` are written against those portable interfaces and are intended to lift cleanly into a KMP `commonMain` source set if/when the `sentry` core gains multiplatform targets. Classes in `io.sentry.android.sqlite` are Android-only by construction and will stay where they are.
+
+Note that the module artifact itself (`sentry-android-sqlite`) is currently an Android-only AAR regardless of package layout.

sentry-android-sqlite/api/sentry-android-sqlite.api

@@ -21,3 +21,16 @@ public final class io/sentry/android/sqlite/SentrySupportSQLiteOpenHelper$Compan
 	public final fun create (Landroidx/sqlite/db/SupportSQLiteOpenHelper;)Landroidx/sqlite/db/SupportSQLiteOpenHelper;
 }
 
+public final class io/sentry/sqlite/SentrySQLiteDriver : androidx/sqlite/SQLiteDriver {
+	public static final field Companion Lio/sentry/sqlite/SentrySQLiteDriver$Companion;
+	public synthetic fun <init> (Landroidx/sqlite/SQLiteDriver;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public static final fun create (Landroidx/sqlite/SQLiteDriver;)Landroidx/sqlite/SQLiteDriver;
+	public fun getHasConnectionPool ()Z
+	public synthetic fun hasConnectionPool ()Z
+	public fun open (Ljava/lang/String;)Landroidx/sqlite/SQLiteConnection;
+}
+
+public final class io/sentry/sqlite/SentrySQLiteDriver$Companion {
+	public final fun create (Landroidx/sqlite/SQLiteDriver;)Landroidx/sqlite/SQLiteDriver;
+}
+

sentry-android-sqlite/src/main/java/io/sentry/android/sqlite/SQLiteSpanManager.kt

@@ -3,21 +3,17 @@ package io.sentry.android.sqlite
 import android.database.CrossProcessCursor
 import android.database.SQLException
 import io.sentry.IScopes
-import io.sentry.ISpan
-import io.sentry.Instrumenter
 import io.sentry.ScopesAdapter
 import io.sentry.SentryIntegrationPackageStorage
-import io.sentry.SentryStackTraceFactory
-import io.sentry.SpanDataConvention
 import io.sentry.SpanStatus
-
-private const val TRACE_ORIGIN = "auto.db.sqlite"
+import io.sentry.sqlite.SQLiteSpanInstrumentation
 
 internal class SQLiteSpanManager(
   private val scopes: IScopes = ScopesAdapter.getInstance(),
-  private val databaseName: String? = null,
+  databaseName: String? = null,
 ) {
-  private val stackTraceFactory = SentryStackTraceFactory(scopes.options)
+
+  private val spans = SQLiteSpanInstrumentation.fromDatabaseName(databaseName, scopes)
 
   init {
     SentryIntegrationPackageStorage.getInstance().addIntegration("SQLite")
@@ -33,8 +29,8 @@ internal class SQLiteSpanManager(
   @Suppress("TooGenericExceptionCaught", "UNCHECKED_CAST")
   @Throws(SQLException::class)
   fun <T> performSql(sql: String, operation: () -> T): T {
-    val startTimestamp = scopes.getOptions().dateProvider.now()
-    var span: ISpan? = null
+    val startTimestamp = spans.startTimestamp()
+
     return try {
       val result = operation()
       /*
@@ -45,34 +41,11 @@ internal class SQLiteSpanManager(
       if (result is CrossProcessCursor) {
         return SentryCrossProcessCursor(result, this, sql) as T
       }
-      span = scopes.span?.startChild("db.sql.query", sql, startTimestamp, Instrumenter.SENTRY)
-      span?.spanContext?.origin = TRACE_ORIGIN
-      span?.status = SpanStatus.OK
+      spans.recordSpan(sql, startTimestamp, SpanStatus.OK)
       result
     } catch (e: Throwable) {
-      span = scopes.span?.startChild("db.sql.query", sql, startTimestamp, Instrumenter.SENTRY)
-      span?.spanContext?.origin = TRACE_ORIGIN
-      span?.status = SpanStatus.INTERNAL_ERROR
-      span?.throwable = e
+      spans.recordSpan(sql, startTimestamp, SpanStatus.INTERNAL_ERROR, e)
       throw e
-    } finally {
-      span?.apply {
-        val isMainThread: Boolean = scopes.options.threadChecker.isMainThread
-        setData(SpanDataConvention.BLOCKED_MAIN_THREAD_KEY, isMainThread)
-        if (isMainThread) {
-          setData(SpanDataConvention.CALL_STACK_KEY, stackTraceFactory.inAppCallStack)
-        }
-        // if db name is null, then it's an in-memory database as per
-        // https://cs.android.com/androidx/platform/frameworks/support/+/androidx-main:sqlite/sqlite/src/main/java/androidx/sqlite/db/SupportSQLiteOpenHelper.kt;l=38-42
-        if (databaseName != null) {
-          setData(SpanDataConvention.DB_SYSTEM_KEY, "sqlite")
-          setData(SpanDataConvention.DB_NAME_KEY, databaseName)
-        } else {
-          setData(SpanDataConvention.DB_SYSTEM_KEY, "in-memory")
-        }
-
-        finish()
-      }
     }
   }
 }

sentry-android-sqlite/src/main/java/io/sentry/sqlite/DbMetadata.kt

@@ -0,0 +1,55 @@
+package io.sentry.sqlite
+
+/**
+ * Value associated with [DB_SYSTEM_KEY][io.sentry.SpanDataConvention.DB_SYSTEM_KEY] for in-memory
+ * databases.
+ */
+internal const val DB_SYSTEM_IN_MEMORY = "in-memory"
+
+/**
+ * Value associated with [DB_SYSTEM_KEY][io.sentry.SpanDataConvention.DB_SYSTEM_KEY] for SQLite
+ * databases.
+ */
+internal const val DB_SYSTEM_SQLITE = "sqlite"
+
+/**
+ * Sentinel file name that [SQLiteDriver.open][androidx.sqlite.SQLiteDriver.open] interprets as an
+ * in-memory database:
+ * https://developer.android.com/reference/androidx/sqlite/driver/AndroidSQLiteDriver.
+ */
+private const val IN_MEMORY_DB_FILENAME = ":memory:"
+
+/** Path separators matching [File.separatorChar][java.io.File.separatorChar]. */
+private val FILE_NAME_PATH_SEPARATORS = charArrayOf('/', '\\')
+
+internal data class DbMetadata(val name: String?, val system: String)
+
+/**
+ * Resolves metadata from the [fileName] argument to
+ * [SQLiteDriver.open][androidx.sqlite.SQLiteDriver.open].
+ */
+internal fun dbMetadataFromFileName(fileName: String): DbMetadata {
+  if (fileName == IN_MEMORY_DB_FILENAME) {
+    return DbMetadata(name = null, system = DB_SYSTEM_IN_MEMORY)
+  }
+
+  val trimmed = fileName.trimEnd { it in FILE_NAME_PATH_SEPARATORS }
+  if (trimmed.isEmpty()) {
+    return DbMetadata(name = null, system = DB_SYSTEM_SQLITE)
+  }
+
+  val index = trimmed.lastIndexOfAny(FILE_NAME_PATH_SEPARATORS)
+  val basename = if (index >= 0) trimmed.substring(index + 1) else trimmed
+  return DbMetadata(name = basename.ifEmpty { null }, system = DB_SYSTEM_SQLITE)
+}
+
+/**
+ * Resolves metadata from
+ * [SupportSQLiteOpenHelper.databaseName][androidx.sqlite.db.SupportSQLiteOpenHelper.databaseName].
+ */
+internal fun dbMetadataFromDatabaseName(databaseName: String?): DbMetadata =
+  if (databaseName == null) {
+    DbMetadata(name = null, system = DB_SYSTEM_IN_MEMORY)
+  } else {
+    DbMetadata(name = databaseName, system = DB_SYSTEM_SQLITE)
+  }

sentry-android-sqlite/src/main/java/io/sentry/sqlite/SQLiteSpanInstrumentation.kt

@@ -0,0 +1,85 @@
+package io.sentry.sqlite
+
+import io.sentry.IScopes
+import io.sentry.Instrumenter
+import io.sentry.ScopesAdapter
+import io.sentry.SentryDate
+import io.sentry.SentryLongDate
+import io.sentry.SentryStackTraceFactory
+import io.sentry.SpanDataConvention
+import io.sentry.SpanStatus
+
+private const val SQLITE_TRACE_ORIGIN = "auto.db.sqlite"
+
+/** Shared span creation and metadata for SQLite instrumentation. */
+internal class SQLiteSpanInstrumentation(
+  private val scopes: IScopes,
+  private val dbMetadata: DbMetadata,
+) {
+
+  private val stackTraceFactory = SentryStackTraceFactory(scopes.options)
+
+  /**
+   * Returns a start timestamp for a `db.sql.query` span.
+   *
+   * Exposed so callers can capture a wall-clock start before accumulating database time.
+   * Internalizing the start time in [recordSpan] would shift spans to end-of-work on the trace
+   * timeline, which is less desirable.
+   */
+  fun startTimestamp(): SentryDate = scopes.options.dateProvider.now()
+
+  /** Records a `db.sql.query` span from [startTimestamp] to the moment of invocation. */
+  fun recordSpan(
+    sql: String,
+    startTimestamp: SentryDate,
+    status: SpanStatus,
+    throwable: Throwable? = null,
+  ) {
+    recordSpan(sql, startTimestamp, endTimestamp = null, status, throwable)
+  }
+
+  /** Records a `db.sql.query` span from [startTimestamp] to [startTimestamp] + [durationNanos]. */
+  fun recordSpan(
+    sql: String,
+    startTimestamp: SentryDate,
+    durationNanos: Long,
+    status: SpanStatus,
+    throwable: Throwable? = null,
+  ) {
+    val endTimestamp = SentryLongDate(startTimestamp.nanoTimestamp() + durationNanos)
+    recordSpan(sql, startTimestamp, endTimestamp, status, throwable)
+  }
+
+  private fun recordSpan(
+    sql: String,
+    startTimestamp: SentryDate,
+    endTimestamp: SentryDate?,
+    status: SpanStatus,
+    throwable: Throwable?,
+  ) {
+    scopes.span?.startChild("db.sql.query", sql, startTimestamp, Instrumenter.SENTRY)?.apply {
+      spanContext.origin = SQLITE_TRACE_ORIGIN
+      throwable?.let { this.throwable = it }
+
+      val isMainThread = scopes.options.threadChecker.isMainThread
+      setData(SpanDataConvention.BLOCKED_MAIN_THREAD_KEY, isMainThread)
+
+      if (isMainThread) {
+        setData(SpanDataConvention.CALL_STACK_KEY, stackTraceFactory.inAppCallStack)
+      }
+
+      dbMetadata.name?.let { setData(SpanDataConvention.DB_NAME_KEY, it) }
+      setData(SpanDataConvention.DB_SYSTEM_KEY, dbMetadata.system)
+      finish(status, endTimestamp)
+    }
+  }
+
+  companion object {
+
+    fun fromDatabaseName(databaseName: String?, scopes: IScopes = ScopesAdapter.getInstance()) =
+      SQLiteSpanInstrumentation(scopes, dbMetadataFromDatabaseName(databaseName))
+
+    fun fromFileName(fileName: String, scopes: IScopes = ScopesAdapter.getInstance()) =
+      SQLiteSpanInstrumentation(scopes, dbMetadataFromFileName(fileName))
+  }
+}

sentry-android-sqlite/src/main/java/io/sentry/sqlite/SentrySQLiteConnection.kt

@@ -0,0 +1,15 @@
+package io.sentry.sqlite
+
+import androidx.sqlite.SQLiteConnection
+import androidx.sqlite.SQLiteStatement
+
+internal class SentrySQLiteConnection(
+  private val delegate: SQLiteConnection,
+  private val spans: SQLiteSpanInstrumentation,
+) : SQLiteConnection by delegate {
+
+  override fun prepare(sql: String): SQLiteStatement {
+    val statement = delegate.prepare(sql)
+    return statement as? SentrySQLiteStatement ?: SentrySQLiteStatement(statement, spans, sql)
+  }
+}