Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,10 @@

## Unreleased

### Features

- Nav3: Add `BackStackEntryMapper.SerialName`, a convenience mapper that names back stack entries after their kotlinx.serialization serial names ([#6703](https://github.com/getsentry/sentry-java/pull/6703))

### Behavioral Changes

- Nav3: If a back stack entry's arguments contain a map with two keys that are recorded as the same string (e.g., `1` and `"1"`), Sentry now drops that entry's arguments and records `dropped_by_sentry: duplicate_key`, instead of keeping only one of the values ([#6701](https://github.com/getsentry/sentry-java/pull/6701))
Expand Down
1 change: 1 addition & 0 deletions gradle/libs.versions.toml
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,7 @@ kotlin-spring = { id = "org.jetbrains.kotlin.plugin.spring", version.ref = "kotl
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" }
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", 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.ref = "dokka" }
Expand Down
15 changes: 15 additions & 0 deletions gradle/nav3.versions.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Versions for sentry-android-navigation3's kotlinx.serialization compatibility checks, registered as
# the `nav3Libs` catalog.
#
# Kept apart from libs.versions.toml so that the Nav3 R8 check workflow can run on PRs that change
# them without also running on every unrelated dependency bump.

[versions]
# The oldest kotlinx.serialization version sentry-android-navigation3 supports, which it compiles and
# tests against. Nav3 builds apply it explicitly rather than via version.ref to prevent Dependabot
# from modifying it. When updating, also update MIN_KOTLINX_SERIALIZATION_VERSION in
# KotlinxMapperDiagnostics (KotlinxBackStackEntryMapper.kt); a unit test fails if the two don't match.
kotlinxSerializationFloor = "1.7.3"

[libraries]
kotlinx-serialization-core = { module = "org.jetbrains.kotlinx:kotlinx-serialization-core" }
2 changes: 1 addition & 1 deletion sentry-android-navigation3/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Use `SentryNavEffect` alongside your `NavDisplay` to record navigation transacti
users move around your app. Configure the data you want captured via `SentryNavOptions`.

Because Nav3 back stacks can have arbitrary key types, host apps need to provide `SentryNavEffect` with a mapping between their back stack
keys and the data Sentry should display for each (see `BackStackEntryMapper`).
keys and the data Sentry should display for each (see `BackStackEntryMapper` and the built-in `SerialName` mapper).

See the [Navigation for Android docs](https://docs.sentry.io/platforms/android/integrations/navigation/) for additional details, including
configuration, supported setups, and limitations.
Original file line number Diff line number Diff line change
@@ -1,7 +1,12 @@
public abstract interface class io/sentry/compose/navigation3/BackStackEntryMapper {
public static final field Companion Lio/sentry/compose/navigation3/BackStackEntryMapper$Companion;
public abstract fun map (Ljava/lang/Object;)Lio/sentry/compose/navigation3/SentryBackStackEntry;
}

public final class io/sentry/compose/navigation3/BackStackEntryMapper$Companion {
public final fun getSerialName ()Lio/sentry/compose/navigation3/BackStackEntryMapper;
}

public final class io/sentry/compose/navigation3/BuildConfig {
public static final field BUILD_TYPE Ljava/lang/String;
public static final field DEBUG Z
Expand Down
21 changes: 20 additions & 1 deletion sentry-android-navigation3/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ plugins {
alias(libs.plugins.kotlin.android)
alias(libs.plugins.kotlin.compose)
alias(libs.plugins.gradle.versions)
alias(libs.plugins.kotlin.serialization)
id("io.sentry.detekt")
id("io.sentry.spotless")
id("io.sentry.jdk-target")
Expand All @@ -15,6 +16,8 @@ plugins {
id("io.sentry.robolectric")
}

val kotlinxSerializationFloor = nav3Libs.versions.kotlinxSerializationFloor.get()

android {
compileSdk = libs.versions.compileSdk.get().toInt()
namespace = "io.sentry.compose.navigation3"
Expand Down Expand Up @@ -45,6 +48,8 @@ android {
// AGP 9.5 can't create the Compose Preview task without it, which breaks any
// build that creates every task, such as an LSP's Gradle import.
isIncludeAndroidResources = true
// Lets tests check that MIN_KOTLINX_SERIALIZATION_VERSION matches the catalog's floor.
all { it.systemProperty("nav3.kotlinxSerializationFloor", kotlinxSerializationFloor) }
}
}

Expand Down Expand Up @@ -72,12 +77,22 @@ android {

kotlin { explicitApi() }

// Unit tests run against the kotlinx.serialization floor by default. CI also runs them against the
// latest version (-Pnav3TestKotlinxVersion=<version>), as apps may ship a newer
// kotlinx.serialization dependency than sentry-android-navigation3 compiles against.
val testKotlinxVersion =
providers.gradleProperty("nav3TestKotlinxVersion").orNull ?: kotlinxSerializationFloor

dependencies {
implementation(projects.sentry)
compileOnly(libs.androidx.lifecycle.runtime.compose)

compileOnly(libs.androidx.compose.runtime)
compileOnly(libs.androidx.compose.ui)
compileOnly(libs.androidx.lifecycle.runtime.compose)
// All Nav3 apps depend on kotlinx.serialization via navigation3-runtime.
compileOnly(nav3Libs.kotlinx.serialization.core) {
version { require(kotlinxSerializationFloor) }
}

testImplementation(projects.sentryAndroidCore)
testImplementation(projects.sentryTestSupport)
Expand All @@ -88,6 +103,10 @@ dependencies {
testImplementation(libs.androidx.viewpager2)
testImplementation(libs.google.truth)
testImplementation(libs.kotlin.test.junit)
testImplementation(nav3Libs.kotlinx.serialization.core) {
// Avoid using whatever version test deps happen to pull in transitively.
version { strictly(testKotlinxVersion) }
}
testImplementation(libs.mockito.core)
testImplementation(libs.mockito.kotlin)
testImplementation(libs.roboelectric)
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
package io.sentry.compose.navigation3

import io.sentry.compose.navigation3.internal.backstack.BuiltInBackStackEntryMappers
import org.jetbrains.annotations.ApiStatus

/** Info about a given back stack entry, suitable for display in Sentry. */
Expand Down Expand Up @@ -53,12 +54,16 @@ public class SentryBackStackEntry(
/**
* Maps a back stack entry to a displayable name and optional diagnostic arguments.
*
* To be implemented by the host app.
* If you use kotlinx.serialization, see [SerialName] for convenient, out-of-the-box mappers.
* Otherwise, provide your own implementation. (Note: Custom implementations can always fall back to
* `SerialName` for any entries that don't have to be special-cased.)
*
* **Privacy / PII**
*
* Values returned from [map] are ***not*** scrubbed by the Sentry SDK before being sent to Sentry.
* Only return names and arguments that are known to be safe or have been pre-scrubbed.
* Custom mappers are responsible for filtering their own arguments.
*
* Only return names and arguments that are known to be safe or have been pre-scrubbed. All
* arguments remain subject to size and structural limits.
*
* **Performance**
*
Expand Down Expand Up @@ -91,7 +96,8 @@ public class SentryBackStackEntry(
* - [CharSequence]
* - [Char]
* - [Boolean]
* - any [Number] (`NaN` and infinite values are sent as strings)
* - any [Number] (`NaN` and infinite values are sent as the strings `"NaN"`, `"Infinity"`, and
* `"-Infinity"`, which JSON can represent)
* - enums (via [Enum.name])
* - `null`
*
Expand All @@ -106,46 +112,82 @@ public class SentryBackStackEntry(
*
* **Arguments fall back to `toString()` or nothing**
*
* All non-supported argument types are stringified via `toString()`.
* All non-supported argument types are stringified via `toString()`, as are map keys.
*
* No arguments will be recorded for a back stack entry if [map] throws or returns `null`, or if its
* arguments are cyclic, too deeply nested, or too large. If the SDK drops an entry's arguments, it
* adds a `dropped_by_sentry` field and corresponding reason in the Sentry UI.
*
* **Using kotlinx.serialization**
*
* If your back stack contains `@Serializable` entry types, consider giving each entry an explicit
* `@SerialName` and using its `descriptor.serialName`. For performance reasons, don't serialize
* back stack keys in their entirety as `arguments` if they might be large, deeply nested, or
* contain PII or other sensitive information.
*
* For instance:
* ```kotlin
* @Serializable
* @SerialName("Home")
* data class Home(val userName: String) : NavKey
*
* @Serializable
* @SerialName("ProductDetail")
* data class ProductDetail(val userName: String, val productId: String) : NavKey
*
* ...
*
* val backStackItemMapper = BackStackEntryMapper<NavKey> { entry ->
* when (entry) {
* is Home -> SentryBackStackEntry(Home.serializer().descriptor.serialName)
* is ProductDetail -> SentryBackStackEntry(
* name = ProductDetail.serializer().descriptor.serialName,
* // Select a subset of diagnostic arguments when serialization is unsafe
* // or non-performant.
* arguments = mapOf("product_id" to entry.productId)
* )
* ...
* }
* }
* ```
* arguments are cyclic, too deeply nested, or too large, or contain a map with two keys that are
* stringified the same way (e.g., `1` and `"1"`). If the SDK drops an entry's arguments, it adds a
* `dropped_by_sentry` field and corresponding reason (e.g., `duplicate_key`) in the Sentry UI.
*/
@ApiStatus.Experimental
public fun interface BackStackEntryMapper<T : Any> {
public fun interface BackStackEntryMapper<in T : Any> {

public fun map(backStackEntry: T): SentryBackStackEntry?

public companion object {

/**
* A convenience [BackStackEntryMapper] for apps that use kotlinx.serialization and only need to
* track the serial name of each of their back stack entries (and not each entry's properties).
*
* For instance, given:
* ```
* @Serializable
* @SerialName("ProductDetail")
* data class ProductDetail(
* val userId: String,
* val productId: String
* ) : NavKey
* ```
*
* when navigating to `ProductDetail(userId = "123abc", productId = "zyx987")`, this mapper
* would return `"ProductDetail"` as the destination's name, but would ***not*** return the
* destination's properties (`userId` and `productId`).
*
* **Name == SerialDescriptor.serialName**
*
* This mapper names each back stack entry after the entry's
* [`SerialDescriptor.serialName`][kotlinx.serialization.descriptors.SerialDescriptor.serialName],
* i.e.:
*
* - the entry's `@SerialName` if it has one; or else
* - the entry's fully qualified class name (e.g., "com.example.Home").
*
* **Unknown names**
*
* This mapper returns `null` for an entry, which Sentry displays as `"/unknown"`, if:
*
* - the entry class isn't annotated with `@Serializable` itself, even if kotlinx.serialization
* can serialize it without the annotation (e.g., `String`, `List`, an unannotated enum, or a
* class marked with a custom `@MetaSerializable` annotation);
*
* - the entry class is generic (e.g., `SettingsScreen<T>`), as its serializer needs type
* arguments that can't be recovered from the entry at runtime; or
*
* - looking up the entry's serializer fails, e.g., because a custom serializer throws, R8
* removed what the lookup needs, or the app's kotlinx.serialization version is incompatible
* with this SDK.
*
* The first entry of each class that can't be named logs a warning explaining why, visible when
* the SDK's `debug` option is enabled. For fixes, see
* [Troubleshooting](https://docs.sentry.io/platforms/android/integrations/navigation/#troubleshooting-kotlinxserialization-mappers)
* in the Sentry Android Navigation docs.
*
* **Sharing names**
*
* Entries share a Sentry name whenever their serializers share a serial name. In particular:
*
* - All constants of an enum are named after the enum. A `@SerialName` on a constant does not
* change the destination name.
*
* - Classes that use the same custom serializer (`@Serializable(with = ...)`) are named after
* that serializer's descriptor, which ignores a `@SerialName` on the class.
*
* To tell such entries apart, define a custom [BackStackEntryMapper], e.g., one that names enum
* constants after [Enum.name].
*/
@get:ApiStatus.Experimental
public val SerialName: BackStackEntryMapper<Any>
get() = BuiltInBackStackEntryMappers.serialName
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,7 @@ import org.jetbrains.annotations.ApiStatus
* // destination are attributed to the appropriate nav transaction.
* SentryNavEffect(
* backStack = navBackStack,
* backStackEntryMapper = { entry ->
* SentryBackStackEntry(entry.toName(), entry.extractArguments())
* },
* backStackEntryMapper = BackStackEntryMapper.SerialName,
* options = SentryNavOptions(),
* )
*
Expand Down
Loading
Loading