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

gradle/libs.versions.toml

@@ -94,7 +94,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)
+  }
+}