feat(plugin): Auto-wrap SQLiteDriver with SentrySQLiteDriver for Room users (GRADLE-107)

Adds a new ASM bytecode method visitor that lets us auto-wrap all occurrences of SQLiteDriver with SentrySQLiteDriver whenever the driver is passed to Room.DatabaseBuilder.setDriver(...).

For instance:

val database = Room.databaseBuilder(context, MyDatabase::class.java, "dbName")
     .setDriver(AndroidSQLiteDriver())
     .build()

becomes:

val database = Room.databaseBuilder(context, MyDatabase::class.java, "dbName")
     .setDriver(SentrySQLiteDriver.create(AndroidSQLiteDriver()))
     .build()

The wrapping policy is naive in that every SQLiteDriver passed to setDriver() is wrapped. That's deliberate because SentrySQLiteDriver protects against double-wrapping internally, which lets us keep our visitor implementation simple.

Preconditions:

1. InstrumentationFeature.DATABASE is enabled
2. The owning app is using a version of sentry-android-sqlite that includes SentrySQLiteDriver

Coverage:

- Auto-wraps SQLiteDriver for all Room users (sole Room access point is via its Room.DatabaseBuilder.setDriver() method).
- SQLDelight users don't need driver auto-wrapping (they still use SupportSQLiteOpenHelper, which we already auto-wrap).
- The few developers who use SQLiteDriver directly will need to wrap it manually.

Author: 0xadam-brown

CHANGELOG.md

@@ -2,16 +2,22 @@
 
 ## Unreleased
 
-### Dependencies
+### Features
 
-- Bump mockito-kotlin from `com.nhaarman.mockitokotlin2:2.2.0` to `org.mockito.kotlin:5.4.0` ([#1286](https://github.com/getsentry/sentry-android-gradle-plugin/pull/1286))
+- Auto-instrument SQLiteDriver for Room users ([#1285](https://github.com/getsentry/sentry-android-gradle-plugin/pull/1285))
+  - Gated on `sentry-android-sqlite` >= 8.44.0 and the existing `tracingInstrumentation` `DATABASE` feature
+  - For users of the `androidx.sqlite.driver.SupportSQLiteDriver` bridge, auto-instrumentation wraps only the `SupportSQLiteOpenHelper` consumed by the bridge and not the bridge itself (avoids duplicate spans)
 
 ### Fixes
 
 - Resolve the sentry-cli path as a task input instead of memoizing it in a static field, fixing stale-path build failures when switching branches with the configuration cache enabled ([#1264](https://github.com/getsentry/sentry-android-gradle-plugin/pull/1264))
   - This fixed the issue where sentry-cli could not be found (`A problem occurred starting process 'command  ../sentry-cliXXX.exe'`)
 - Defer the telemetry default-org lookup to execution time so the configuration cache no longer re-runs `sentry-cli` on every build ([#1263](https://github.com/getsentry/sentry-android-gradle-plugin/pull/1263))
 
+### Dependencies
+
+- Bump mockito-kotlin from `com.nhaarman.mockitokotlin2:2.2.0` to `org.mockito.kotlin:5.4.0` ([#1286](https://github.com/getsentry/sentry-android-gradle-plugin/pull/1286))
+
 ## 6.10.0
 
 ### Features

gradle/libs.versions.toml

@@ -63,6 +63,9 @@ sentrySpringBootJakarta = { group = "io.sentry", name = "sentry-spring-boot-star
 mockitoKotlin = { group = "org.mockito.kotlin", name = "mockito-kotlin", version = "5.4.0" }
 arscLib = { group = "io.github.reandroid", name = "ARSCLib", version = "1.1.4" }
 zip4j = { group = "net.lingala.zip4j", name = "zip4j", version = "2.11.5" }
+# Versions must match RoomDatabase$Builder bytecode fixtures (see SQLiteDriverBytecodeTestUtil).
+roomRuntimeAndroid = { group = "androidx.room", name = "room-runtime-android", version = "2.7.0" }
+room3RuntimeAndroid = { group = "androidx.room3", name = "room3-runtime-android", version = "3.0.0-alpha06" }
 
 # samples
 sample-androidx-recyclerView = "androidx.recyclerview:recyclerview:1.2.0"

plugin-build/build.gradle.kts

@@ -55,12 +55,17 @@ dependencies {
   testImplementation(libs.asmCommons)
 
   // we need these dependencies for tests, because the bytecode verifier also analyzes superclasses
+  testImplementationAar(libs.roomRuntimeAndroid)
+  testImplementationAar(libs.room3RuntimeAndroid)
+  testImplementationAar(libs.sentryAndroid)
+  testImplementationAar(libs.sentryAndroidOkhttp)
   testImplementationAar(libs.sqlite)
   testImplementationAar(libs.sqliteFramework)
-  testRuntimeOnly(files(androidSdkPath))
-  testImplementationAar(libs.sentryAndroid)
+
+  testImplementation(libs.sample.coroutines.core)
   testImplementation(libs.sentryOkhttp)
-  testImplementationAar(libs.sentryAndroidOkhttp)
+
+  testRuntimeOnly(files(androidSdkPath))
 
   // Needed to read contents from APK/Source Bundles
   testImplementation(libs.arscLib)

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

@@ -75,9 +75,19 @@ open class TracingInstrumentationExtension @Inject constructor(objects: ObjectFa
 
 enum class InstrumentationFeature(val integrationName: String) {
   /**
-   * When enabled the SDK will create spans for any CRUD operation performed by
-   * 'androidx.sqlite.db.SupportSQLiteOpenHelper' and 'androidx.room'. This feature uses bytecode
-   * manipulation.
+   * When enabled the SDK will create spans for database operations at two levels:
+   *
+   * **SQL execution** (`db.sql.query` spans): wraps the low-level driver so each individual SQL
+   * statement produces a span. Two mutually exclusive paths:
+   * - `androidx.sqlite.db.SupportSQLiteOpenHelper` via any `SupportSQLiteOpenHelper.Factory`
+   *   (open-helper path)
+   * - `androidx.sqlite.SQLiteDriver` via `RoomDatabase.Builder.setDriver` (driver path)
+   *
+   * **DAO method** (`db.sql.room` spans): wraps each public method on Room's generated `@Dao`
+   * `_Impl` classes, measuring the full DAO call end-to-end (transaction management, query
+   * execution, and cursor processing). Pre-Room 2.7 only.
+   *
+   * This feature uses bytecode manipulation.
    */
   DATABASE("DatabaseInstrumentation"),
 

plugin-build/src/main/kotlin/io/sentry/android/gradle/instrumentation/SpanAddingClassVisitorFactory.kt

@@ -10,6 +10,7 @@ import io.sentry.android.gradle.instrumentation.androidx.compose.ComposeNavigati
 import io.sentry.android.gradle.instrumentation.androidx.room.AndroidXRoomDao
 import io.sentry.android.gradle.instrumentation.androidx.sqlite.AndroidXSQLiteOpenHelper
 import io.sentry.android.gradle.instrumentation.androidx.sqlite.database.AndroidXSQLiteDatabase
+import io.sentry.android.gradle.instrumentation.androidx.sqlite.driver.AndroidXSQLiteDriver
 import io.sentry.android.gradle.instrumentation.androidx.sqlite.statement.AndroidXSQLiteStatement
 import io.sentry.android.gradle.instrumentation.appstart.Application
 import io.sentry.android.gradle.instrumentation.appstart.ContentProvider
@@ -90,10 +91,12 @@ abstract class SpanAddingClassVisitorFactory :
         ChainedInstrumentable(
           listOfNotNull(
             AndroidXSQLiteOpenHelper().takeIf { sentryModulesService.isNewDatabaseInstrEnabled() },
+            AndroidXSQLiteDriver().takeIf { sentryModulesService.isSQLiteDriverInstrEnabled() },
             AndroidXSQLiteDatabase().takeIf { sentryModulesService.isOldDatabaseInstrEnabled() },
             AndroidXSQLiteStatement(androidXSqliteFrameWorkVersion).takeIf {
               sentryModulesService.isOldDatabaseInstrEnabled()
             },
+            // Note that DAO spans no longer work on Room 2.7+ or Room 3.0+ due to Room API changes.
             AndroidXRoomDao().takeIf {
               sentryModulesService.isNewDatabaseInstrEnabled() ||
                 sentryModulesService.isOldDatabaseInstrEnabled()

plugin-build/src/main/kotlin/io/sentry/android/gradle/instrumentation/androidx/sqlite/driver/AndroidXSQLiteDriver.kt

@@ -0,0 +1,74 @@
+package io.sentry.android.gradle.instrumentation.androidx.sqlite.driver
+
+import com.android.build.api.instrumentation.ClassContext
+import io.sentry.android.gradle.instrumentation.ClassInstrumentable
+import io.sentry.android.gradle.instrumentation.CommonClassVisitor
+import io.sentry.android.gradle.instrumentation.MethodContext
+import io.sentry.android.gradle.instrumentation.MethodInstrumentable
+import io.sentry.android.gradle.instrumentation.SpanAddingClassVisitorFactory
+import io.sentry.android.gradle.instrumentation.androidx.sqlite.driver.visitor.SetDriverMethodVisitor
+import org.objectweb.asm.ClassVisitor
+import org.objectweb.asm.MethodVisitor
+
+/**
+ * Auto-instruments `SQLiteDriver` for all Room users by wrapping the driver parameter in
+ * `RoomDatabase.Builder.setDriver(SQLiteDriver)`.
+ *
+ * Note: As of this writing, SQLDelight doesn't support `SQLiteDriver`
+ * ([link](https://github.com/sqldelight/sqldelight/issues/6072)), and developers who use the driver
+ * directly are expected to wrap it themselves.
+ *
+ * The SDK protects against duplicate wrappings, allowing the visitor to wrap the driver
+ * unconditionally.
+ */
+class AndroidXSQLiteDriver : ClassInstrumentable {
+
+  override fun getVisitor(
+    instrumentableContext: ClassContext,
+    apiVersion: Int,
+    originalVisitor: ClassVisitor,
+    parameters: SpanAddingClassVisitorFactory.SpanAddingParameters,
+  ): ClassVisitor {
+    val currentClassName = instrumentableContext.currentClassData.className
+
+    return CommonClassVisitor(
+      apiVersion = apiVersion,
+      classVisitor = originalVisitor,
+      className = currentClassName.substringAfterLast('.'),
+      methodInstrumentables = listOf(SetDriverMethodInstrumentable()),
+      parameters = parameters,
+    )
+  }
+
+  // Instrument RoomDatabase.Builder.setDriver() in room-runtime and room3 directly.
+  override fun isInstrumentable(data: ClassContext): Boolean =
+    data.currentClassData.className in TARGET_CLASSES
+
+  companion object {
+
+    /** Currently covers Room 2 and Room 3 packages. Update as needed. */
+    internal val TARGET_CLASSES =
+      setOf("androidx.room.RoomDatabase\$Builder", "androidx.room3.RoomDatabase\$Builder")
+  }
+}
+
+class SetDriverMethodInstrumentable : MethodInstrumentable {
+
+  override val fqName: String
+    get() = SET_DRIVER
+
+  override fun getVisitor(
+    instrumentableContext: MethodContext,
+    apiVersion: Int,
+    originalVisitor: MethodVisitor,
+    parameters: SpanAddingClassVisitorFactory.SpanAddingParameters,
+  ): MethodVisitor = SetDriverMethodVisitor(apiVersion, originalVisitor, instrumentableContext)
+
+  override fun isInstrumentable(data: MethodContext): Boolean =
+    data.name == SET_DRIVER && data.descriptor?.startsWith(SET_DRIVER_DESCRIPTOR_PREFIX) == true
+
+  companion object {
+    internal const val SET_DRIVER = "setDriver"
+    internal const val SET_DRIVER_DESCRIPTOR_PREFIX = "(Landroidx/sqlite/SQLiteDriver;)"
+  }
+}

plugin-build/src/main/kotlin/io/sentry/android/gradle/instrumentation/androidx/sqlite/driver/visitor/SetDriverMethodVisitor.kt

@@ -0,0 +1,34 @@
+package io.sentry.android.gradle.instrumentation.androidx.sqlite.driver.visitor
+
+import io.sentry.android.gradle.instrumentation.MethodContext
+import org.objectweb.asm.MethodVisitor
+import org.objectweb.asm.Type
+import org.objectweb.asm.commons.AdviceAdapter
+import org.objectweb.asm.commons.Method
+
+class SetDriverMethodVisitor(
+  apiVersion: Int,
+  originalVisitor: MethodVisitor,
+  instrumentableContext: MethodContext,
+) :
+  AdviceAdapter(
+    apiVersion,
+    originalVisitor,
+    instrumentableContext.access,
+    instrumentableContext.name,
+    instrumentableContext.descriptor,
+  ) {
+
+  override fun onMethodEnter() {
+    loadArg(0)
+    invokeStatic(Type.getType(SENTRY_SQLITE_DRIVER_TYPE), Method(CREATE, SENTRY_CREATE_DESCRIPTOR))
+    storeArg(0)
+  }
+
+  companion object {
+    internal const val CREATE = "create"
+    internal const val SENTRY_CREATE_DESCRIPTOR =
+      "(Landroidx/sqlite/SQLiteDriver;)Landroidx/sqlite/SQLiteDriver;"
+    internal const val SENTRY_SQLITE_DRIVER_TYPE = "Lio/sentry/sqlite/SentrySQLiteDriver;"
+  }
+}

plugin-build/src/main/kotlin/io/sentry/android/gradle/services/SentryModulesService.kt

@@ -72,6 +72,19 @@ abstract class SentryModulesService :
     sentryModules.isAtLeast(SentryModules.SENTRY_ANDROID_SQLITE, SentryVersions.VERSION_SQLITE) &&
       parameters.features.get().contains(InstrumentationFeature.DATABASE)
 
+  /**
+   * Returns true when the owning app uses a version of sentry-android-sqlite that contains
+   * `SentrySQLiteDriver` and the DATABASE feature is enabled.
+   *
+   * Room version is not gated here: Room < 2.7 has no matching `setDriver` method, so
+   * instrumentation is a no-op. Method descriptor matching is the safety boundary.
+   */
+  fun isSQLiteDriverInstrEnabled(): Boolean =
+    sentryModules.isAtLeast(
+      SentryModules.SENTRY_ANDROID_SQLITE,
+      SentryVersions.VERSION_SQLITE_DRIVER,
+    ) && parameters.features.get().contains(InstrumentationFeature.DATABASE)
+
   fun isOldDatabaseInstrEnabled(): Boolean =
     !isNewDatabaseInstrEnabled() &&
       sentryModules.isAtLeast(

plugin-build/src/main/kotlin/io/sentry/android/gradle/util/Versions.kt

@@ -33,6 +33,7 @@ internal object SentryVersions {
   internal val VERSION_LOGCAT = SemVer(6, 17, 0)
   internal val VERSION_APP_START = SemVer(7, 1, 0)
   internal val VERSION_SQLITE = SemVer(6, 21, 0)
+  internal val VERSION_SQLITE_DRIVER = SemVer(8, 44, 0)
   internal val VERSION_ANDROID_OKHTTP_LISTENER = SemVer(6, 20, 0)
   internal val VERSION_OKHTTP = SemVer(7, 0, 0)
 }

plugin-build/src/test/kotlin/androidx/sqlite/SQLiteDriver.kt

@@ -0,0 +1,3 @@
+package androidx.sqlite
+
+interface SQLiteDriver