Skip to content
Open
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
10 changes: 5 additions & 5 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,22 +10,22 @@
### 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))
- Nav3: Add `BackStackEntryMapper.SerialNameAndProperties`, which is like `SerialName` except that it also records the properties of each back stack entry as arguments ([#6706](https://github.com/getsentry/sentry-java/pull/6706))

### 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))

### Dependencies

- Nav3: `sentry-android-navigation3` no longer declares a dependency on `androidx.lifecycle:lifecycle-runtime-compose`. Nav3 apps already depend on it via `navigation3-ui`, so no app changes are necessary ([#6699](https://github.com/getsentry/sentry-java/pull/6699))

### Fixes

- Nav3: `NaN` and infinite numbers in back stack entry arguments are now sent as the strings `"NaN"`, `"Infinity"`, and `"-Infinity"`, instead of causing the event they're attached to be dropped ([#6700](https://github.com/getsentry/sentry-java/pull/6700))

- Kotlin now sees `Attachment.getBytes()`, `Device.getArchs()`, `Spring.getActiveProfiles()` and `JsonSerializationUtils.bytesFrom(...)` as nullable, because `@Nullable` now annotates the returned array instead of its elements ([#6558](https://github.com/getsentry/sentry-java/pull/6558))
- Shake-to-report no longer leaks the first Activity that resumes after `Sentry.init` ([#6686](https://github.com/getsentry/sentry-java/pull/6686))

### Dependencies

- Nav3: `sentry-android-navigation3` no longer declares a dependency on `androidx.lifecycle:lifecycle-runtime-compose`. Nav3 apps already depend on it via `navigation3-ui`, so no app changes are necessary ([#6699](https://github.com/getsentry/sentry-java/pull/6699))

## 8.65.0

### Features
Expand Down
3 changes: 2 additions & 1 deletion sentry-android-navigation3/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@ 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` and the built-in `SerialName` mapper).
keys and the data Sentry should display for each (see `BackStackEntryMapper` and the built-in `SerialName` and
`SerialNameAndProperties` mappers).

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
Expand Up @@ -5,6 +5,7 @@ public abstract interface class io/sentry/compose/navigation3/BackStackEntryMapp

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

public final class io/sentry/compose/navigation3/BuildConfig {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -54,13 +54,17 @@ public class SentryBackStackEntry(
/**
* Maps a back stack entry to a displayable name and optional diagnostic arguments.
*
* 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.)
* If you use kotlinx.serialization, see [SerialName] and [SerialNameAndProperties] for convenient,
* out-of-the-box mappers. Otherwise, provide your own implementation. (Note: Custom implementations
* can always fall back to `SerialName` or `SerialNameAndProperties` for any entries that don't have
* to be special-cased.)
*
* **Privacy / PII**
*
* Custom mappers are responsible for filtering their own arguments.
* Built-in mappers that capture entry properties apply limited sensitive-data filtering before
* recording arguments; see [SerialNameAndProperties] for the filtering rules. Custom mappers are
* responsible for filtering their own arguments; Sentry does not apply its built-in sensitive-data
* filtering to arguments they supply themselves.
*
* 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.
Expand Down Expand Up @@ -144,6 +148,8 @@ public fun interface BackStackEntryMapper<in T : Any> {
* would return `"ProductDetail"` as the destination's name, but would ***not*** return the
* destination's properties (`userId` and `productId`).
*
* To return both entry names and properties, see [SerialNameAndProperties].
*
* **Name == SerialDescriptor.serialName**
*
* This mapper names each back stack entry after the entry's
Expand Down Expand Up @@ -177,8 +183,8 @@ public fun interface BackStackEntryMapper<in T : Any> {
*
* 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.
* - All constants of an enum are named after the enum. A `@SerialName` on a constant only
* changes how [SerialNameAndProperties] records the constant as an argument.
*
* - Classes that use the same custom serializer (`@Serializable(with = ...)`) are named after
* that serializer's descriptor, which ignores a `@SerialName` on the class.
Expand All @@ -189,5 +195,72 @@ public fun interface BackStackEntryMapper<in T : Any> {
@get:ApiStatus.Experimental
public val SerialName: BackStackEntryMapper<Any>
get() = BuiltInBackStackEntryMappers.serialName

/**
* Like [SerialName], but also returns the properties of each back stack entry as Sentry
* arguments.
*
* 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, along with the following arguments:
* ```json
* {
* "userId": "123abc",
* "productId": "zyx987"
* }
* ```
*
* Returns `null` for any entries that can't be named (see [SerialName]). Sentry displays these
* entries as `"/unknown"` with no arguments.
*
* The argument limits described in [BackStackEntryMapper] apply.
*
* **Privacy / PII**
*
* This mapper returns arguments for every property of each back stack entry passed to it, which
* may include private data or PII. Almost all properties are sent as-is (see below for limited
* exceptions in the case of sensitive secrets). Neither `sendDefaultPii` nor the
* `dataCollection` options change what this mapper returns.
*
* Modify your use of this mapper if any entry in your back stack contains info you don't want
* sent to Sentry. For instance, i) use this mapper for all entries but filter out any
* properties you want to omit, or ii) use a custom [BackStackEntryMapper] that special-cases
* entries with sensitive info or PII and falls back to this mapper (or [SerialName]) for
* entries without it. See
* [Choosing Which Arguments to Send](https://docs.sentry.io/platforms/android/integrations/navigation/#choosing-which-arguments-to-send)
* for examples.
*
* **Limited filtering for sensitive secrets**
*
* Values are replaced with `"[Filtered]"` when their property's targeted name (i.e., their
* `@SerialName` if they have one, or else the property's name) contains a term from
* [Sentry's sensitive denylist](https://develop.sentry.dev/sdk/foundations/client/data-collection/#sensitive-denylist)
* (ignoring case). This filters secrets like `authToken`, but leaves PII like `userEmail`
* unchanged.
*
* Matching follows the same rule Sentry SDKs use for HTTP headers, cookies, and query
* parameters, meaning it may filter harmless properties like `insideCart` (`sid`) or `keyword`
* (`key`).
*
* **Encoding and encoding failures**
*
* Properties are encoded on the first argument read, including by `equals` or `hashCode`.
*
* Failures preserve the entry's name and replace its arguments with a drop reason, e.g.,
* `{"dropped_by_sentry": "encoding_failed"}`. Encoding errors are logged once per entry type
* when `debug` is enabled.
*/
@get:ApiStatus.Experimental
public val SerialNameAndProperties: BackStackEntryMapper<Any>
get() = BuiltInBackStackEntryMappers.serialNameAndProperties
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,52 @@ import java.util.IdentityHashMap
* implementations are expected to materialize the provided info into a tree of Sentry arguments,
* where the tree has a bounded size and height.
*
* **The argument conversion subsystem**
*
* With Nav3, host apps manage their own nav back stack, which they implement as a list of
* arbitrarily typed entries. In order to be displayed in Sentry, each of those entries has to be
* mapped to a Sentry name (e.g., ProductDetailScreen) and zero or more arguments (e.g., productId).
* There are two ways for host apps to provide us with those mappings:
*
* 1. via a custom `BackStackEntryMapper`; or
*
* 2. via one of our own built-in mappers (viz., `BackStackEntryMapper.SerialName` or
* `BackStackEntryMapper.SerialNameAndProperties`).
*
* `ArgumentSink` and `ArgumentSource` create the seam that lets us support variable processing on
* the source side (the host app's logic vs built-in logic) but uniform processing on the sink side
* (argument pruning, protecting against constraint violation, and tree materialization).
*
* Here are the moving parts:
* ```text
* ArgumentSource
* Custom mapper Built-in mappers
* ┌────────────────────┐ ┌──────────────────┐
* │ HostArgumentSource │ │ KotlinxArguments │
* │ (plain host map) │ │ (drives encoder) │
* └────────┬───────────┘ └────────┬─────────┘
* │ │ via
* │ KotlinxPropertiesEncoder + SensitiveKeyFilter
* │ │
* └──────────────┬──────────────┘
* ▼
* ┌───────────────────────────────┐
* │ ArgumentSink │
* └───────────────────────────────┘
* ▲ sole impl
* ┌───────────────┴───────────────┐
* │ TreeArgumentWriter │
* │ │ ┌────────────────┐
* │ Enforce + materialize: │ spends ──▶│ ArgumentBudget │
* │ • builds the argument tree │ └────────────────┘
* │ • prevents constraint │ ┌────────────────┐
* │ violation (e.g., cycles) │ throws ──▶│ DropArguments │
* └───────────────────────────────┘ └────────────────┘
*
* Note: BackStackConverter.ArgumentSanitizer owns the ArgumentBudget and
* selects the ArgumentSource based on what the host app provides.
* ```
*
* Receives one back stack entry's arguments as a [source][ArgumentSource] produces them, enforcing
* the argument limits as it goes.
*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,23 @@ internal object BuiltInBackStackEntryMappers {
// threads may each create and probe a mapper and log warnings, and all but the first
// published instance would be discarded.
create(logger) {
KotlinxBackStackEntryMapper(logger = logger)
KotlinxBackStackEntryMapper(includeProperties = false, logger = logger)
}
}

/**
* Like [serialName], but also returns the properties of each back stack entry as Sentry
* arguments.
*
* Falls back to [UnavailableBackStackEntryMapper] if a mapper can't be created.
*
* See [BackStackEntryMapper.SerialNameAndProperties] for more details.
*/
val serialNameAndProperties: BackStackEntryMapper<Any> by
lazy(LazyThreadSafetyMode.PUBLICATION) {
// PUBLICATION, as for serialName.
create(logger) {
KotlinxBackStackEntryMapper(includeProperties = true, logger = logger)
}
}

Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,15 @@
# `io.sentry.compose.navigation3.internal.backstack`

Converts host back stacks into bounded Sentry names and arguments.
Package contains code for generating Sentry data from a host app's back stack.

## Conventions

### Properties vs. arguments

Code in this package uses the term "properties" for the fields and values it reads from a back stack entry and "arguments" for the values
a `BackStackEntryMapper` supplies for Sentry to record, i.e., `SentryBackStackEntry.arguments`. Arguments include the mapper's output before
sanitization, which may modify or drop them before Sentry records them. Hence
`SerialNameAndProperties` and `KotlinxPropertiesEncoder`, but `SentryBackStackEntry(arguments = ...)`.

When a host app uses a built-in `BackStackEntryMapper`, we're responsible for mapping entry properties to corresponding arguments. When the
host app implements its own `BackStackEntryMapper`, it performs the mapping on its end and hands the resulting arguments to us.
Loading
Loading