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 Room that supports SQLiteDriver
3. 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,6 +2,12 @@
 
 ## Unreleased
 
+### Features
+
+- Auto-wrap SQLiteDriver with SentrySQLiteDriver for Room users ([#1285](https://github.com/getsentry/sentry-android-gradle-plugin/pull/1285))
+  - Gated on i) `sentry-android-sqlite` >= 8.44.0, ii) `androidx.room:room-runtime` >= 2.7.0-alpha01 or `androidx.room3:room3-runtime` >= 3.0.0-alpha01, and iii) the existing `tracingInstrumentation` `DATABASE` feature
+  - For users of the `androidx.sqlite.driver.SupportSQLiteDriver` bridge, the `SupportSQLiteOpenHelper` consumed by the bridge continues to be auto-wrapped as before rather than the bridge itself being wrapped
+
 ### 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))

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,6 +91,7 @@ abstract class SpanAddingClassVisitorFactory :
         ChainedInstrumentable(
           listOfNotNull(
             AndroidXSQLiteOpenHelper().takeIf { sentryModulesService.isNewDatabaseInstrEnabled() },
+            AndroidXSQLiteDriver().takeIf { sentryModulesService.isSQLiteDriverInstrEnabled() },
             AndroidXSQLiteDatabase().takeIf { sentryModulesService.isOldDatabaseInstrEnabled() },
             AndroidXSQLiteStatement(androidXSqliteFrameWorkVersion).takeIf {
               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 {
+    private const val SET_DRIVER = "setDriver"
+    private 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 {
+    private const val SENTRY_SQLITE_DRIVER_TYPE = "Lio/sentry/sqlite/SentrySQLiteDriver;"
+    private const val CREATE = "create"
+    private const val SENTRY_CREATE_DESCRIPTOR =
+      "(Landroidx/sqlite/SQLiteDriver;)Landroidx/sqlite/SQLiteDriver;"
+  }
+}

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

@@ -4,6 +4,8 @@ package io.sentry.android.gradle.services
 
 import com.android.build.gradle.internal.utils.setDisallowChanges
 import io.sentry.android.gradle.extensions.InstrumentationFeature
+import io.sentry.android.gradle.util.ExternalModules
+import io.sentry.android.gradle.util.ExternalVersions
 import io.sentry.android.gradle.util.SemVer
 import io.sentry.android.gradle.util.SentryModules
 import io.sentry.android.gradle.util.SentryVersions
@@ -52,6 +54,10 @@ abstract class SentryModulesService :
       features.add("DexGuard")
     }
 
+    if (isSQLiteDriverInstrEnabled()) {
+      features.add("SQLiteDriver")
+    }
+
     return project.provider { features }
   }
 
@@ -72,6 +78,30 @@ abstract class SentryModulesService :
     sentryModules.isAtLeast(SentryModules.SENTRY_ANDROID_SQLITE, SentryVersions.VERSION_SQLITE) &&
       parameters.features.get().contains(InstrumentationFeature.DATABASE)
 
+  fun isSQLiteDriverInstrEnabled(): Boolean =
+    isSQLiteDriverSentryGateEnabled() && isSQLiteDriverRoomGateEnabled()
+
+  /**
+   * Returns true if the owning app uses a version of sentry-android-sqlite that contains the
+   * `SentrySQLiteDriver`.
+   */
+  private fun isSQLiteDriverSentryGateEnabled(): Boolean =
+    sentryModules.isAtLeast(
+      SentryModules.SENTRY_ANDROID_SQLITE,
+      SentryVersions.VERSION_SQLITE_DRIVER,
+    ) && parameters.features.get().contains(InstrumentationFeature.DATABASE)
+
+  /** Returns true if the owning app uses on a version of Room that supports `SQLiteDriver`. */
+  private fun isSQLiteDriverRoomGateEnabled(): Boolean =
+    externalModules.isAtLeastMinor(
+      ExternalModules.ROOM2_RUNTIME,
+      ExternalVersions.ROOM2_SQLITE_DRIVER_VERSION,
+    ) ||
+      externalModules.isAtLeastMinor(
+        ExternalModules.ROOM3_RUNTIME,
+        ExternalVersions.ROOM3_SQLITE_DRIVER_VERSION,
+      )
+
   fun isOldDatabaseInstrEnabled(): Boolean =
     !isNewDatabaseInstrEnabled() &&
       sentryModules.isAtLeast(
@@ -121,6 +151,21 @@ abstract class SentryModulesService :
     minVersion: SemVer,
   ): Boolean = getOrDefault(module, SentryVersions.VERSION_DEFAULT) >= minVersion
 
+  /**
+   * External-library gate on major.minor only, irrespective of patch or pre-release. Pre-releases
+   * on the floor line pass (e.g. Room `2.7.0-alpha12` satisfies a `2.7.0` floor).
+   *
+   * Not equivalent to `>=`, as full [SemVer] ordering ranks pre-releases below the release.
+   */
+  private fun Map<ModuleIdentifier, SemVer>.isAtLeastMinor(
+    module: ModuleIdentifier,
+    minVersion: SemVer,
+  ): Boolean {
+    val version = getOrDefault(module, SentryVersions.VERSION_DEFAULT)
+    return version.major > minVersion.major ||
+      (version.major == minVersion.major && version.minor >= minVersion.minor)
+  }
+
   companion object {
     fun register(
       project: Project,

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

@@ -33,10 +33,21 @@ 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)
 }
 
+internal object ExternalVersions {
+  // Room 2.7.0 introduced RoomDatabase.Builder.setDriver(SQLiteDriver) in the androidx.room
+  // package.
+  internal val ROOM2_SQLITE_DRIVER_VERSION = SemVer(2, 7, 0)
+
+  // Room 3.0 moved the RoomDatabase.Builder.setDriver(SQLiteDriver) to the androidx.room3
+  // package.
+  internal val ROOM3_SQLITE_DRIVER_VERSION = SemVer(3, 0, 0)
+}
+
 internal object SentryModules {
   internal val SENTRY = DefaultModuleIdentifier.newId("io.sentry", "sentry")
   internal val SENTRY_ANDROID = DefaultModuleIdentifier.newId("io.sentry", "sentry-android")
@@ -80,3 +91,8 @@ internal object SentryModules {
   internal val SENTRY_OPENTELEMETRY_AGENTLESS_SPRING =
     DefaultModuleIdentifier.newId("io.sentry", "sentry-opentelemetry-agentless-spring")
 }
+
+internal object ExternalModules {
+  internal val ROOM2_RUNTIME = DefaultModuleIdentifier.newId("androidx.room", "room-runtime")
+  internal val ROOM3_RUNTIME = DefaultModuleIdentifier.newId("androidx.room3", "room3-runtime")
+}

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

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

plugin-build/src/test/kotlin/io/sentry/android/gradle/instrumentation/VisitorTest.kt

@@ -5,6 +5,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
@@ -122,6 +123,18 @@ class VisitorTest(
           AndroidXSQLiteStatement(SemVer(2, 3, 0)),
           null,
         ),
+        arrayOf(
+          "androidxRoom",
+          "RoomDatabase\$Builder",
+          AndroidXSQLiteDriver(),
+          TestClassContext("androidx.room.RoomDatabase\$Builder"),
+        ),
+        arrayOf(
+          "androidxRoom",
+          "RoomDatabase3\$Builder",
+          AndroidXSQLiteDriver(),
+          TestClassContext("androidx.room3.RoomDatabase\$Builder"),
+        ),
         roomDaoTestParameters("DeleteAndReturnUnit"),
         roomDaoTestParameters("InsertAndReturnLong"),
         roomDaoTestParameters("InsertAndReturnUnit"),

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

@@ -0,0 +1,71 @@
+@file:Suppress("UnstableApiUsage")
+
+package io.sentry.android.gradle.instrumentation.androidx.sqlite.driver
+
+import io.sentry.android.gradle.instrumentation.ChainedInstrumentable
+import io.sentry.android.gradle.instrumentation.fakes.TestClassContext
+import io.sentry.android.gradle.instrumentation.fakes.TestSpanAddingParameters
+import java.io.FileInputStream
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertTrue
+import org.junit.Rule
+import org.junit.Test
+import org.junit.rules.TemporaryFolder
+import org.objectweb.asm.ClassReader
+import org.objectweb.asm.ClassWriter
+import org.objectweb.asm.Opcodes
+
+class AndroidXSQLiteDriverTest {
+
+  @get:Rule val tmpDir = TemporaryFolder()
+
+  private val instrumentable = AndroidXSQLiteDriver()
+
+  @Test
+  fun `isInstrumentable returns true for RoomDatabase Builder classes`() {
+    assertTrue(
+      instrumentable.isInstrumentable(TestClassContext("androidx.room.RoomDatabase\$Builder"))
+    )
+    assertTrue(
+      instrumentable.isInstrumentable(TestClassContext("androidx.room3.RoomDatabase\$Builder"))
+    )
+  }
+
+  @Test
+  fun `isInstrumentable returns false for unrelated classes`() {
+    assertFalse(instrumentable.isInstrumentable(TestClassContext("com.example.RoomConfig")))
+    assertFalse(instrumentable.isInstrumentable(TestClassContext("io.sentry.Sentry")))
+    assertFalse(instrumentable.isInstrumentable(TestClassContext("com.example.FakeSetDriver")))
+  }
+
+  @Test
+  fun `ChainedInstrumentable does not instrument unrelated classes`() {
+    val className = "com.example.NoSetDriver"
+    val originalBytes = loadNoSetDriverFixtureBytes()
+    val instrumentedBytes = instrumentThroughChain(className, originalBytes)
+
+    assertEquals(0, SQLiteDriverBytecodeTestUtil.countWrapCalls(instrumentedBytes))
+  }
+
+  private fun instrumentThroughChain(className: String, bytes: ByteArray): ByteArray {
+    val classReader = ClassReader(bytes)
+    val classWriter = ClassWriter(classReader, ClassWriter.COMPUTE_MAXS)
+    val classVisitor =
+      ChainedInstrumentable(listOf(instrumentable))
+        .getVisitor(
+          TestClassContext(className),
+          Opcodes.ASM9,
+          classWriter,
+          parameters = TestSpanAddingParameters(inMemoryDir = tmpDir.root),
+        )
+    classReader.accept(classVisitor, ClassReader.SKIP_FRAMES)
+    return classWriter.toByteArray()
+  }
+
+  private fun loadNoSetDriverFixtureBytes(): ByteArray =
+    FileInputStream(
+        "src/test/resources/testFixtures/instrumentation/androidxSqliteDriver/NoSetDriver.class"
+      )
+      .use { it.readBytes() }
+}