feat(android-sqlite): Add SentrySQLiteDriver (JAVA-275) (#5466)

feat(android-sqlite): Add SentrySQLiteDriver (JAVA-275)

Introduces support for AndroidX's SQLiteDriver via a new SentrySQLiteDriver wrapper.

SentrySQLiteDriver automatically creates spans for each SQL statement it executes. Its data scheme closely tracks that of SentrySupportSQLiteOpenHelper, which it's designed to replace. (Span duration is an important exception; see the SentrySQLiteStatement KDoc for more details.)

A key motivation behind Google's use of SQLiteDriver with Room 2.7+ was Kotlin Multiplatform support. We're careful to keep the SentrySQLiteDriver KMP-compatible as well, should we one day want to lift it into sentry-kotlin-multiplatform.

---

Co-authored-by: Angus Holder <7407345+angusholder@users.noreply.github.com>

Author: 0xadam-brown

gradle/libs.versions.toml

@@ -95,7 +95,7 @@ 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-sqlite = { module = "androidx.sqlite:sqlite", version = "2.6.2" }
 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" }

sentry-android-sqlite/README.md

@@ -0,0 +1,21 @@
+# sentry-android-sqlite
+
+SQLite instrumentation for AndroidX APIs.
+
+Two instrumentation paths are supported:
+
+- **`androidx.sqlite.SQLiteDriver`**: Used by Room 2.7+ and 3.0+.
+- **`androidx.sqlite.db.SupportSQLiteOpenHelper`**: Used by SQLDelight and legacy (pre-2.7) Room. Applied automatically by the Sentry Android Gradle Plugin.
+
+To avoid duplicate spans, only one path should be used per database file. Most Room and SQLDelight APIs enforce that division. The exception is Room's `SupportSQLiteDriver`: either the `SupportSQLiteOpenHelper` it consumes should be wrapped or the support driver itself, but never both.
+
+## Package layout
+
+The module is organized as two separate packages:
+
+- **`io.sentry.android.sqlite`**: Android-specific code. Depends on `android.database.*` and/or on `androidx.sqlite.db.*`.
+- **`io.sentry.sqlite`**: No Android-specific code. Depends only on multiplatform `androidx.sqlite.*`.
+
+The split anticipates future Kotlin Multiplatform support. The `androidx.sqlite.*` interfaces are defined in KMP's `commonMain` source set and are used by Room in non-JVM environments. 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.
+
+Note that the module artifact itself (`sentry-android-sqlite`) is currently an Android-only AAR regardless of package layout.

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,49 @@
+package io.sentry.sqlite
+
+/** [DB_SYSTEM_KEY][io.sentry.SpanDataConvention.DB_SYSTEM_KEY] value for in-memory databases. */
+internal const val DB_SYSTEM_IN_MEMORY = "in-memory"
+
+/** [DB_SYSTEM_KEY][io.sentry.SpanDataConvention.DB_SYSTEM_KEY] value 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 (see docs
+ * [here](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)
+
+/**
+ * Returns metadata based on the [fileName] argument passed 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)
+}
+
+/**
+ * Returns metadata based on
+ * [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,99 @@
+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 instrumentation for SQLite. */
+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 {
+
+    /**
+     * Returns [SQLiteSpanInstrumentation] based on the [fileName] argument passed to
+     * [SQLiteDriver.open][androidx.sqlite.SQLiteDriver.open].
+     */
+    fun fromFileName(
+      fileName: String,
+      scopes: IScopes = ScopesAdapter.getInstance(),
+    ): SQLiteSpanInstrumentation =
+      SQLiteSpanInstrumentation(scopes, dbMetadataFromFileName(fileName))
+
+    /**
+     * Returns [SQLiteSpanInstrumentation] based on
+     * [SupportSQLiteOpenHelper.databaseName][androidx.sqlite.db.SupportSQLiteOpenHelper.databaseName].
+     */
+    fun fromDatabaseName(
+      databaseName: String?,
+      scopes: IScopes = ScopesAdapter.getInstance(),
+    ): SQLiteSpanInstrumentation =
+      SQLiteSpanInstrumentation(scopes, dbMetadataFromDatabaseName(databaseName))
+  }
+}

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)
+  }
+}

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

@@ -0,0 +1,79 @@
+package io.sentry.sqlite
+
+import androidx.sqlite.SQLiteConnection
+import androidx.sqlite.SQLiteDriver
+import io.sentry.ScopesAdapter
+import io.sentry.SentryIntegrationPackageStorage
+import io.sentry.SentryLevel
+
+/**
+ * Wraps a [SQLiteDriver] and automatically adds spans for each SQL statement it executes.
+ *
+ * Example usage:
+ * ```
+ * val driver = SentrySQLiteDriver.create(AndroidSQLiteDriver())
+ * ```
+ *
+ * If you use Room:
+ * ```
+ * val database = Room.databaseBuilder(context, MyDatabase::class.java, "dbName")
+ *     .setDriver(SentrySQLiteDriver.create(AndroidSQLiteDriver()))
+ *     .build()
+ * ```
+ *
+ * **Warning:** Do not use [SentrySQLiteDriver] together with
+ * [SentrySupportSQLiteOpenHelper][io.sentry.android.sqlite.SentrySupportSQLiteOpenHelper] on the
+ * same database file. Both wrappers instrument at different layers and combining them will produce
+ * duplicate spans.
+ *
+ * @param delegate The [SQLiteDriver] instance to delegate calls to.
+ */
+internal class SentrySQLiteDriver private constructor(private val delegate: SQLiteDriver) :
+  SQLiteDriver {
+
+  init {
+    SentryIntegrationPackageStorage.getInstance().addIntegration("SQLiteDriver")
+  }
+
+  override val hasConnectionPool: Boolean
+    get() =
+      try {
+        delegate.hasConnectionPool
+      } catch (_: LinkageError) {
+        // Delegates on androidx.sqlite < 2.6.0 won't have a hasConnectionPool property.
+        false
+      }
+
+  @Suppress("TooGenericExceptionCaught")
+  override fun open(fileName: String): SQLiteConnection {
+    val connection = delegate.open(fileName)
+
+    return try {
+      val spans = SQLiteSpanInstrumentation.fromFileName(fileName)
+      // create() ensures delegate is unwrapped, so we don't need to protect against double-wrapping
+      // the connection.
+      SentrySQLiteConnection(connection, spans)
+    } catch (t: Throwable) {
+      ScopesAdapter.getInstance()
+        .options
+        .logger
+        .log(
+          SentryLevel.ERROR,
+          "Failed to instrument SQLite connection; returning uninstrumented connection.",
+          t,
+        )
+      connection
+    }
+  }
+
+  companion object {
+
+    /**
+     * Wraps the provided delegate in a [SentrySQLiteDriver]. Returns the delegate as-is if already
+     * wrapped.
+     */
+    @JvmStatic
+    fun create(delegate: SQLiteDriver): SQLiteDriver =
+      delegate as? SentrySQLiteDriver ?: SentrySQLiteDriver(delegate)
+  }
+}