Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(Android): Add docs for Sentry Kotlin Compiler Plugin #7026

Merged
merged 7 commits into from
Jun 5, 2023
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,25 @@
<meta-data android:name="io.sentry.attach-view-hierarchy" android:value="true" />
</application>
```

### Jetpack Compose Support using the Sentry Kotlin Compiler Plugin

<Note>

The Sentry Kotlin Compiler plugin is considered _experimental_. Give it a try and provide early feedback [on GitHub](https://github.com/getsentry/sentry-android-gradle-plugin).

</Note>

If your application uses Jetpack Compose, you can use the <PlatformLink to="/kotlin-compiler-plugin/">Sentry Kotlin Compiler Plugin</PlatformLink> to see the function names of your `@Composable` elements. You must add the plugin to all modules that contain `@Composable` elements.

```groovy {filename:app/build.gradle}
plugins {
id "io.sentry.kotlin.compiler.gradle" version "{{@inject packages.version('sentry.kotlin.compiler-plugin', '3.0.0') }}"
markushi marked this conversation as resolved.
Show resolved Hide resolved
}
```

```kotlin {filename:app/build.gradle.kts}
plugins {
id("io.sentry.kotlin.compiler.gradle") version "{{@inject packages.version('sentry.kotlin.compiler-plugin', '3.0.0') }}"
}
```
markushi marked this conversation as resolved.
Show resolved Hide resolved
2 changes: 1 addition & 1 deletion src/platforms/android/common/gradle.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Gradle
sidebar_order: 100
sidebar_order: 98
description: "Learn about using the Sentry Android Gradle Plugin."
---

Expand Down
66 changes: 66 additions & 0 deletions src/platforms/android/common/kotlin-compiler-plugin.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
---
title: Kotlin Compiler Plugin
sidebar_order: 99
description: "Learn about using the Sentry Kotlin Compiler Plugin."
---

The [Sentry Kotlin Compiler Plugin](https://github.com/getsentry/sentry-android-gradle-plugin) is an addition to the Sentry Android Gradle plugin and offers improvements to existing SDK features. As of now the main focus of the plugin is to improve apps which utilize Jetpack Compose by automatically tagging `@Composable` functions.

- <PlatformLink to="/enriching-events/viewhierarchy">
View Hierarchy
</PlatformLink>
- <PlatformLink to="/performance/instrumentation/automatic-instrumentation/#user-interaction-instrumentation">
User Interaction Tracing
</PlatformLink>

<Note>

The Sentry Kotlin Compiler plugin is considered _experimental_. Give it a try and provide early feedback [on GitHub](https://github.com/getsentry/sentry-android-gradle-plugin).

</Note>

## How it works

Given a `@Composable` function:

```kotlin
@Composable
fun LoginScreen() {
Column() {
// ...
}
}
```

The Sentry Kotlin Compiler Plugin will transform it into the following:

```kotlin
@Composable
fun LoginScreen() {
Column(modifier = Modifier.sentryTag("LoginScreen")) {
// ...
}
}
```

## Setup

### Install

Kotlin Compiler plugins are executed during compilation and thus need to be applied to _every_ relevant Gradle module. Add the following to e.g. your `app/build.gradle`:

```groovy {filename:app/build.gradle}
plugins {
id "io.sentry.kotlin.compiler.gradle" version "{{@inject packages.version('sentry.kotlin.compiler-plugin', '3.0.0') }}"
}
```

```kotlin {filename:app/build.gradle.kts}
plugins {
id("io.sentry.kotlin.compiler.gradle") version "{{@inject packages.version('sentry.kotlin.compiler-plugin', '3.0.0') }}"
}
```

### Configuration

As of now no additional steps are necessary. Checkout the docs for <PlatformLink to="/enriching-events/viewhierarchy">View Hierarchy</PlatformLink> and <PlatformLink to="/performance/instrumentation/automatic-instrumentation/#user-interaction-instrumentation">User Interaction Tracing</PlatformLink> to see which features the Sentry Kotlin Compiler Plugin improves.
Original file line number Diff line number Diff line change
Expand Up @@ -273,10 +273,32 @@ fun LoginScreen() {

<Note>

If the `@Composable` doesn't have a `testTag` modifier applied, the transaction won't be captured because it can't be uniquely identified otherwise.
If the `@Composable` doesn't have a `testTag` modifier applied, the transaction won't be captured because it can't be uniquely identified. To capture a transaction for the `@Composable`, you must either add a `testTag` modifier or enable automatic `@Composable` tagging.

</Note>

##### Automatic `@Composable` tagging using the Sentry Kotlin Compiler Plugin

<Note>

The Sentry Kotlin Compiler plugin is considered _experimental_. Give it a try and provide early feedback [on GitHub](https://github.com/getsentry/sentry-android-gradle-plugin).

</Note>

The <PlatformLink to="/kotlin-compiler-plugin/">Sentry Kotlin Compiler Plugin</PlatformLink> can automatically enrich your `@Composable` functions during compilation with a tag name, based on the function name of your `@Composable`. In order to use this feature, the Sentry Kotlin Compiler plugin needs to be applied to all modules, which contain `@Composable` elements.

```groovy {filename:app/build.gradle}
plugins {
id "io.sentry.kotlin.compiler.gradle" version "{{@inject packages.version('sentry.kotlin.compiler-plugin', '3.0.0') }}"
}
```

```kotlin {filename:app/build.gradle.kts}
plugins {
id("io.sentry.kotlin.compiler.gradle") version "{{@inject packages.version('sentry.kotlin.compiler-plugin', '3.0.0') }}"
}
```

#### Transaction Lifetime

The transaction finishes automatically after it reaches the specified [idleTimeout](/platforms/android/configuration/options/#idle-timeout) and all of its child spans are finished. The `idleTimeoout` defaults to `3000` milliseconds (three seconds). You can also disable the idle timeout by setting it to `null`, but the transaction must be finished manually in this case.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ The `sentry-compose-android` library provides [Jetpack Compose](https://develope
- `@Composable` performance metrics
- Transaction and breadcrumb support for user interactions (clicks, swipes and scroll gestures)
- Transaction and breadcrumb support for navigation events
- Support for <PlatformLink to="/enriching-events/viewhierarchy/">View Hierarchies</PlatformLink>

## Performance Metrics

Expand Down Expand Up @@ -131,7 +132,7 @@ fun LoginScreen() {

<Note>

If a `@Composable` doesn't have a `testTag` modifier applied, both breadcrumbs and transactions won't be captured because they can't be uniquely identified.
If a `@Composable` doesn't have a `testTag` modifier applied, both breadcrumbs and transactions won't be captured because they can't be uniquely identified. To automatically generate tags, refer to the docs about our <PlatformLink to="/kotlin-compiler-plugin/">Sentry Kotlin Compiler Plugin</PlatformLink>.

</Note>

Expand Down