From f24e0aa675be94872ca567504107a254b2309238 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 9 Mar 2023 14:23:04 +0100 Subject: [PATCH 01/11] add initial kmp platform setup --- .../capture-error/kotlin-multiplatform.mdx | 5 + .../capture-message/kotlin-multiplatform.mdx | 5 + .../config-intro/kotlin-multiplatform.mdx | 12 + .../drain-example/kotlin-multiplatform.mdx | 1 + .../add-attachment/kotlin-multiplatform.mdx | 17 + .../kotlin-multiplatform.mdx | 7 + .../kotlin-multiplatform.mdx | 7 + .../kotlin-multiplatform.mdx | 6 + .../kotlin-multiplatform.mdx | 16 + .../kotlin-multiplatform.mdx | 38 ++ .../kotlin-multiplatform.mdx | 14 + .../configure-scope/kotlin-multiplatform.mdx | 12 + .../kotlin-multiplatform.mdx | 13 + .../set-context/kotlin-multiplatform.mdx | 9 + .../set-tag/kotlin-multiplatform.mdx | 7 + .../set-user/kotlin-multiplatform.mdx | 1 + .../unset-user/kotlin-multiplatform.mdx | 7 + .../sdk-api-example/kotlin-multiplatform.mdx | 13 + .../kotlin-multiplatform.mdx | 11 + .../kotlin-multiplatform.mdx | 29 ++ .../kotlin-multiplatform.mdx | 5 + .../kotlin-multiplatform.mdx | 9 + .../set-environment/kotlin-multiplatform.mdx | 8 + .../set-level/kotlin-multiplatform.mdx | 8 + .../set-release/kotlin-multiplatform.mdx | 9 + .../common/configuration/filtering.mdx | 1 + .../data-management/sensitive-data/index.mdx | 4 +- .../enriching-events/attachments/index.mdx | 8 +- .../enriching-events/event-processors.mdx | 1 + .../common/enriching-events/scopes.mdx | 4 +- .../common/enriching-events/screenshots.mdx | 11 + .../common/enriching-events/user-feedback.mdx | 4 +- src/platforms/common/index.mdx | 2 +- .../common/usage/sdk-fingerprinting.mdx | 1 + src/platforms/kotlin-multiplatform/config.yml | 9 + .../kotlin-multiplatform/migration.mdx | 398 ++++++++++++++++++ 36 files changed, 701 insertions(+), 11 deletions(-) create mode 100644 src/platform-includes/capture-error/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/capture-message/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/configuration/config-intro/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/configuration/drain-example/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/enriching-events/add-attachment/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/enriching-events/attach-screenshots/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/enriching-events/attachment-init-with-bytes/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/enriching-events/attachment-init-with-path/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/enriching-events/attachment-upload/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/enriching-events/breadcrumbs/breadcrumbs-example/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/enriching-events/scopes/configure-scope/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/enriching-events/scopes/scope-callback-param/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/enriching-events/set-context/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/enriching-events/set-tag/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/enriching-events/set-user/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/enriching-events/unset-user/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/enriching-events/user-feedback/sdk-api-example/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/getting-started-config/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/getting-started-install/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/getting-started-verify/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/set-environment/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/set-level/kotlin-multiplatform.mdx create mode 100644 src/platform-includes/set-release/kotlin-multiplatform.mdx create mode 100644 src/platforms/kotlin-multiplatform/config.yml create mode 100644 src/platforms/kotlin-multiplatform/migration.mdx diff --git a/src/platform-includes/capture-error/kotlin-multiplatform.mdx b/src/platform-includes/capture-error/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..cfff99bfea086 --- /dev/null +++ b/src/platform-includes/capture-error/kotlin-multiplatform.mdx @@ -0,0 +1,5 @@ +```kotlin +import io.sentry.kotlin.multiplatform.Sentry + +Sentry.captureException(exception) +``` diff --git a/src/platform-includes/capture-message/kotlin-multiplatform.mdx b/src/platform-includes/capture-message/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..0c0dcbf49f38d --- /dev/null +++ b/src/platform-includes/capture-message/kotlin-multiplatform.mdx @@ -0,0 +1,5 @@ +```kotlin +import io.sentry.kotlin.multiplatform.Sentry + +Sentry.captureMessage("Something went wrong") +``` diff --git a/src/platform-includes/configuration/config-intro/kotlin-multiplatform.mdx b/src/platform-includes/configuration/config-intro/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..f7b418ce83ba7 --- /dev/null +++ b/src/platform-includes/configuration/config-intro/kotlin-multiplatform.mdx @@ -0,0 +1,12 @@ + + If Android is a target in your application, the application context is needed for initialization. + + +```kotlin +import io.sentry.kotlin.multiplatform.Sentry + +Sentry.init(context) { options -> + options.dsn = "___PUBLIC_DSN___" + options.release = "io.sentry.samples@3.0.0+1" +} +``` diff --git a/src/platform-includes/configuration/drain-example/kotlin-multiplatform.mdx b/src/platform-includes/configuration/drain-example/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..187144a06123b --- /dev/null +++ b/src/platform-includes/configuration/drain-example/kotlin-multiplatform.mdx @@ -0,0 +1 @@ +The Kotlin Multiplatform SDK utilises the native SDKs to automatically store Sentry events on the device's disk before shutdown. diff --git a/src/platform-includes/enriching-events/add-attachment/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/add-attachment/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..d68507e4b9ea0 --- /dev/null +++ b/src/platform-includes/enriching-events/add-attachment/kotlin-multiplatform.mdx @@ -0,0 +1,17 @@ +To add an attachment, you can either add it to the scope or pass it to any of the `capture` methods. + +### Passing Attachments to Capture + +You may pass attachments to any of the `capture` methods, for example, when capturing an exception: + +```kotlin +import io.sentry.kotlin.multiplatform.Attachment +import io.sentry.kotlin.multiplatform.Sentry + +val fileAttachment = Attachment("your/path/file.log") + +Sentry.captureException(IllegalStateException()) { scope -> + scope.addAttachment(fileAttachment) +} +``` +// TODO: max attachment size diff --git a/src/platform-includes/enriching-events/attach-screenshots/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/attach-screenshots/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..848257ffd2972 --- /dev/null +++ b/src/platform-includes/enriching-events/attach-screenshots/kotlin-multiplatform.mdx @@ -0,0 +1,7 @@ +```kotlin +import io.sentry.kotlin.multiplatform.Sentry + +Sentry.init { options -> + options.attachScreenshot = true +} +``` diff --git a/src/platform-includes/enriching-events/attachment-init-with-bytes/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/attachment-init-with-bytes/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..095a176f61c41 --- /dev/null +++ b/src/platform-includes/enriching-events/attachment-init-with-bytes/kotlin-multiplatform.mdx @@ -0,0 +1,7 @@ +```kotlin +import io.sentry.kotlin.multiplatform.Sentry +import io.sentry.kotlin.multiplatform.Attachment + +val attachment = Attachment(bytes, "file.log") +``` +// TODO: byte attachment diff --git a/src/platform-includes/enriching-events/attachment-init-with-path/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/attachment-init-with-path/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..08f8c232176dc --- /dev/null +++ b/src/platform-includes/enriching-events/attachment-init-with-path/kotlin-multiplatform.mdx @@ -0,0 +1,6 @@ +```kotlin +import io.sentry.kotlin.multiplatform.Sentry +import io.sentry.kotlin.multiplatform.Attachment + +val attachment = Attachment("your/path/file.log") +``` diff --git a/src/platform-includes/enriching-events/attachment-upload/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/attachment-upload/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..6e70607f38508 --- /dev/null +++ b/src/platform-includes/enriching-events/attachment-upload/kotlin-multiplatform.mdx @@ -0,0 +1,16 @@ +```kotlin +import io.sentry.kotlin.multiplatform.Sentry +import io.sentry.kotlin.multiplatform.Attachment + +val fileAttachment = Attachment("your/path/file.log") + +// Global Scope +Sentry.configureScope { scope -> + scope.addAttachment(fileAttachment) +} + +// Clear all attachments in the global Scope +Sentry.configureScope { scope -> + scope.clearAttachments() +} +``` diff --git a/src/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..d066a7aa19a0d --- /dev/null +++ b/src/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/kotlin-multiplatform.mdx @@ -0,0 +1,38 @@ +```kotlin +import io.sentry.kotlin.multiplatform.Sentry + +Sentry.init { options -> + options.beforeBreadcrumb = { breadcrumb -> + breadcrumb.apply { + if (this.category == "navigation") { + this.message = "Add message to navigation breadcrumb" + } + } + } +} +``` + +## Android +### Disable Automatic Breadcrumbs + +If you want to disable the automatic collection of breadcrumbs on Android, please add the following items into your manifest. + +```xml + + + + + + + + + + + + + + + + +``` +// TODO: cant drop breadcrumbs diff --git a/src/platform-includes/enriching-events/breadcrumbs/breadcrumbs-example/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/breadcrumbs/breadcrumbs-example/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..596b402dff5c9 --- /dev/null +++ b/src/platform-includes/enriching-events/breadcrumbs/breadcrumbs-example/kotlin-multiplatform.mdx @@ -0,0 +1,14 @@ +```kotlin +import io.sentry.kotlin.multiplatform.Sentry +import io.sentry.kotlin.multiplatform.SentryLevel +import io.sentry.kotlin.multiplatform.protocol.Breadcrumb + +val breadcrumb = Breadcrumb().apply { + category = "auth" + message = "Authenticated user ${user.email}" + level = SentryLevel.INFO +} +Sentry.addBreadcrumb(breadcrumb) +``` + +// TODO: addBreadcrumb diff --git a/src/platform-includes/enriching-events/scopes/configure-scope/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/scopes/configure-scope/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..70b661d03c81a --- /dev/null +++ b/src/platform-includes/enriching-events/scopes/configure-scope/kotlin-multiplatform.mdx @@ -0,0 +1,12 @@ +```kotlin +import io.sentry.kotlin.multiplatform.Sentry +import io.sentry.kotlin.multiplatform.protocol.User + +Sentry.configureScope { scope -> + scope.setTag("my-tag", "my value") + scope.user = User().apply { + id = "42" + email = "john.doe@example.com" + } +} +``` diff --git a/src/platform-includes/enriching-events/scopes/scope-callback-param/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/scopes/scope-callback-param/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..02a92f609745c --- /dev/null +++ b/src/platform-includes/enriching-events/scopes/scope-callback-param/kotlin-multiplatform.mdx @@ -0,0 +1,13 @@ +```kotlin +import io.sentry.kotlin.multiplatform.Sentry +import io.sentry.kotlin.multiplatform.SentryLevel + +// will be tagged with my-tag="my value" +Sentry.captureException(Exception("my error")) { scope -> + scope.setTag("my-tag", "my value") + scope.level = SentryLevel.WARNING +} + +// will not be tagged with my-tag +Sentry.captureException(Exception("my error")) +``` diff --git a/src/platform-includes/enriching-events/set-context/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/set-context/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..7afba436617c3 --- /dev/null +++ b/src/platform-includes/enriching-events/set-context/kotlin-multiplatform.mdx @@ -0,0 +1,9 @@ +```kotlin +import io.sentry.kotlin.multiplatform.Sentry + +Sentry.configureScope { scope -> + scope.setContext("name", "Mighty Fighter") + scope.setContext("age", 19) + scope.setContext("attack_type", "melee") +} +``` diff --git a/src/platform-includes/enriching-events/set-tag/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/set-tag/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..49185a2057dc5 --- /dev/null +++ b/src/platform-includes/enriching-events/set-tag/kotlin-multiplatform.mdx @@ -0,0 +1,7 @@ +```kotlin +import io.sentry.kotlin.multiplatform.Sentry + +Sentry.configureScope { scope -> + scope.setTag("page.locale", "de-at") +} +``` diff --git a/src/platform-includes/enriching-events/set-user/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/set-user/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..a188bb0f5ab1f --- /dev/null +++ b/src/platform-includes/enriching-events/set-user/kotlin-multiplatform.mdx @@ -0,0 +1 @@ +// TODO: setUser diff --git a/src/platform-includes/enriching-events/unset-user/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/unset-user/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..dc799f119d629 --- /dev/null +++ b/src/platform-includes/enriching-events/unset-user/kotlin-multiplatform.mdx @@ -0,0 +1,7 @@ +```kotlin {tabTitle: Kotlin} +import io.sentry.kotlin.multiplatform.Sentry + +Sentry.configureScope { scope -> + scope.user = null +} +``` diff --git a/src/platform-includes/enriching-events/user-feedback/sdk-api-example/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/user-feedback/sdk-api-example/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..76a20af3473a7 --- /dev/null +++ b/src/platform-includes/enriching-events/user-feedback/sdk-api-example/kotlin-multiplatform.mdx @@ -0,0 +1,13 @@ +```kotlin +import io.sentry.kotlin.multiplatform.Sentry +import io.sentry.kotlin.multiplatform.protocol.UserFeedback + +val sentryId = Sentry.captureMessage("My message") + +val userFeedback = UserFeedback(sentryId).apply { + comments = "It broke." + email = "john.doe@example.com" + name = "John Doe" +} +Sentry.captureUserFeedback(userFeedback) +``` diff --git a/src/platform-includes/getting-started-config/kotlin-multiplatform.mdx b/src/platform-includes/getting-started-config/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..cef309305ef2c --- /dev/null +++ b/src/platform-includes/getting-started-config/kotlin-multiplatform.mdx @@ -0,0 +1,11 @@ +```kotlin +import io.sentry.kotlin.multiplatform.Context +import io.sentry.kotlin.multiplatform.Sentry + +// The context is needed for Android initializations +fun initializeSentry(context: Context?) { + Sentry.init(context) { + it.dsn = "___PUBLIC_DSN___" + } +} +``` diff --git a/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx b/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..478f2e2466d70 --- /dev/null +++ b/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx @@ -0,0 +1,29 @@ +To install the Kotlin Multiplatform SDK, you need to add the following to your `build.gradle.kts` file in your shared module: + +```kotlin {filename:build.gradle.kt} +repositories { + mavenCentral() +} + +kotlin { + val commonMain by getting { + dependencies { + api("io.sentry:sentry-kotlin-multiplatform:{{ packages.version('sentry.kotlin.kmp', '0.0.1') }}") + } + } + + // If you target Apple platforms: + cocoapods { + summary = "Some description for the Shared Module" + homepage = "Link to the Shared Module homepage" + ios.deploymentTarget = "14.1" + podfile = project.file("../iosApp/Podfile") + pod("Sentry", "~> {{ packages.version('sentry.cocoa', '8.2.0') }}") + + framework { + baseName = "shared" + export("io.sentry:sentry-kotlin-multiplatform:{{ packages.version('sentry.kotlin.kmp', '0.0.1') }}") + } + } + ``` +} diff --git a/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx b/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..284b33d673765 --- /dev/null +++ b/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx @@ -0,0 +1,5 @@ +## Overview of the features + +- Native crash reporting for Android and JVM, leveraging our [Android SDK](/platforms/android) and [Java SDK](/platforms/java) +- Native crash reporting for iOS and macOS, tvOS, watchOS, leveraging our [Cocoa SDK](/platforms/apple) +- Automatic breadcrumbs for native Android and Cocoa app lifecycle and UI events diff --git a/src/platform-includes/getting-started-verify/kotlin-multiplatform.mdx b/src/platform-includes/getting-started-verify/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..4d2a1a1f3a241 --- /dev/null +++ b/src/platform-includes/getting-started-verify/kotlin-multiplatform.mdx @@ -0,0 +1,9 @@ +```kotlin +fun captureError() { + try { + throw Exception("This is a test.") + } catch (e: Exception) { + Sentry.captureException(e) + } +} +``` diff --git a/src/platform-includes/set-environment/kotlin-multiplatform.mdx b/src/platform-includes/set-environment/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..1fbbd63783e7b --- /dev/null +++ b/src/platform-includes/set-environment/kotlin-multiplatform.mdx @@ -0,0 +1,8 @@ +```kotlin +import io.sentry.kotlin.multiplatform.Sentry + +// Context is only needed if you are targeting Android as well +Sentry.init(context) { + it.environment = "production" +} +``` diff --git a/src/platform-includes/set-level/kotlin-multiplatform.mdx b/src/platform-includes/set-level/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..62e75281df790 --- /dev/null +++ b/src/platform-includes/set-level/kotlin-multiplatform.mdx @@ -0,0 +1,8 @@ +```kotlin +import io.sentry.kotlin.multiplatform.Sentry +import io.sentry.kotlin.multiplatform.SentryLevel + +Sentry.configureScope { scope -> + scope.level = SentryLevel.WARNING +} +``` diff --git a/src/platform-includes/set-release/kotlin-multiplatform.mdx b/src/platform-includes/set-release/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..2e7a61ac26cf8 --- /dev/null +++ b/src/platform-includes/set-release/kotlin-multiplatform.mdx @@ -0,0 +1,9 @@ +```kotlin +import io.sentry.kotlin.multiplatform.Sentry + +Sentry.init(androidContext) { options -> + options.release = "io.example@1.1.0" +} +``` + +If no release name is set the SDK creates a default depending on the native platform. diff --git a/src/platforms/common/configuration/filtering.mdx b/src/platforms/common/configuration/filtering.mdx index 43ebaeb39d87d..e3531e7d0a53c 100644 --- a/src/platforms/common/configuration/filtering.mdx +++ b/src/platforms/common/configuration/filtering.mdx @@ -4,6 +4,7 @@ sidebar_order: 60 description: "Learn more about how to configure your SDK to filter events reported to Sentry." notSupported: - perl + - kotlin-multiplatform --- Adding Sentry to your app gives you a great deal of very valuable information about errors and performance you wouldn't otherwise get. And lots of information is good -- as long as it's the right information, at a reasonable volume. diff --git a/src/platforms/common/data-management/sensitive-data/index.mdx b/src/platforms/common/data-management/sensitive-data/index.mdx index 56ea3bbd47c74..df4c891fe39fe 100644 --- a/src/platforms/common/data-management/sensitive-data/index.mdx +++ b/src/platforms/common/data-management/sensitive-data/index.mdx @@ -29,7 +29,7 @@ If you are using Sentry in your mobile app, read our [frequently asked questions - + ## Personally Identifiable Information (PII) @@ -45,7 +45,7 @@ If you _do not_ wish to use the default PII behavior, you can also choose to ide - + ## Scrubbing Data diff --git a/src/platforms/common/enriching-events/attachments/index.mdx b/src/platforms/common/enriching-events/attachments/index.mdx index a96501e984bed..68ca4a35448e1 100644 --- a/src/platforms/common/enriching-events/attachments/index.mdx +++ b/src/platforms/common/enriching-events/attachments/index.mdx @@ -15,7 +15,7 @@ supported: - unreal - react-native - python - + - kotlin-multiplatform --- @@ -58,7 +58,7 @@ To receive symbolicated stack traces, you have to upload debug information to Se - + ## Creating Attachments @@ -86,7 +86,7 @@ In addition, you can set these parameters: ## Uploading Attachments - + @@ -100,7 +100,7 @@ You'll first need to import the SDK, as usual: - + Attachments live on the Scope. You can either add an attachment on the global scope to be sent with every event or add it on the local Scope to just send the attachment with one specific event. diff --git a/src/platforms/common/enriching-events/event-processors.mdx b/src/platforms/common/enriching-events/event-processors.mdx index 3e8fc51c15389..78514a3d76d9a 100644 --- a/src/platforms/common/enriching-events/event-processors.mdx +++ b/src/platforms/common/enriching-events/event-processors.mdx @@ -19,6 +19,7 @@ notSupported: - rust - unity - unreal + - kotlin-multiplatform --- You can enrich events with additional data by adding your own event processors, either on the scope level or globally. Though event processors are similar to and , there are two key differences: diff --git a/src/platforms/common/enriching-events/scopes.mdx b/src/platforms/common/enriching-events/scopes.mdx index cb3d97c6de800..ae1b0cebe26d8 100644 --- a/src/platforms/common/enriching-events/scopes.mdx +++ b/src/platforms/common/enriching-events/scopes.mdx @@ -69,7 +69,7 @@ The Native SDK currently only provides a single scope shared by all threads in t For details on how this affects performance monitoring, check out the [Connect Errors With Spans](/platforms/native/performance/instrumentation/custom-instrumentation/#connect-errors-with-spans) section of "Custom Instrumentation". - + ## Configuring the Scope @@ -141,7 +141,7 @@ caught, and all errors that occur will be silently ignored and **not** reported. - + ### Using Scope Callback Parameter diff --git a/src/platforms/common/enriching-events/screenshots.mdx b/src/platforms/common/enriching-events/screenshots.mdx index 143ce1f95be44..c3c664f266147 100644 --- a/src/platforms/common/enriching-events/screenshots.mdx +++ b/src/platforms/common/enriching-events/screenshots.mdx @@ -10,6 +10,7 @@ supported: - javascript.electron - flutter - react-native + - kotlin-multiplatform notSupported: - apple.macos - apple.tvos @@ -24,6 +25,16 @@ This feature only applies to SDKs with a user interface, such as the ones for mo Screenshots may contain PII and is an opt-in feature. You can enable it as shown below: + + + + +This feature is supported for iOS and Android only. + + + + + diff --git a/src/platforms/common/enriching-events/user-feedback.mdx b/src/platforms/common/enriching-events/user-feedback.mdx index 9ae9bb9a8b6e4..a9aeb9937d9e8 100644 --- a/src/platforms/common/enriching-events/user-feedback.mdx +++ b/src/platforms/common/enriching-events/user-feedback.mdx @@ -20,7 +20,7 @@ While this feature isn't currently supported for Ruby or most of its frameworks, - + ## User Feedback API @@ -66,7 +66,7 @@ SentrySdk.CaptureUserFeedback(eventId, "user@example.com", "It broke.", "The Use - + ## Embeddable JavaScript Widget diff --git a/src/platforms/common/index.mdx b/src/platforms/common/index.mdx index 21b8cc6e5c22b..d620aea0825a0 100644 --- a/src/platforms/common/index.mdx +++ b/src/platforms/common/index.mdx @@ -2,7 +2,7 @@ On this page, we get you up and running with Sentry's SDK, so that it will automatically report errors and exceptions in your application. - + diff --git a/src/platforms/common/usage/sdk-fingerprinting.mdx b/src/platforms/common/usage/sdk-fingerprinting.mdx index 135645c45055d..99927e34e8e0a 100644 --- a/src/platforms/common/usage/sdk-fingerprinting.mdx +++ b/src/platforms/common/usage/sdk-fingerprinting.mdx @@ -11,6 +11,7 @@ notSupported: - unreal - rust - elixir + - kotlin-multiplatform --- All events have a fingerprint. Events with the same fingerprint are grouped together into an issue. diff --git a/src/platforms/kotlin-multiplatform/config.yml b/src/platforms/kotlin-multiplatform/config.yml new file mode 100644 index 0000000000000..8e44c8c28ab62 --- /dev/null +++ b/src/platforms/kotlin-multiplatform/config.yml @@ -0,0 +1,9 @@ +title: Kotlin Multiplatform +caseStyle: camelCase +supportLevel: production +sdk: sentry.kotlin.kmp +fallbackPlatform: java +categories: + - mobile + - desktop +keywords: ["kotlin"] diff --git a/src/platforms/kotlin-multiplatform/migration.mdx b/src/platforms/kotlin-multiplatform/migration.mdx new file mode 100644 index 0000000000000..8a6b321307644 --- /dev/null +++ b/src/platforms/kotlin-multiplatform/migration.mdx @@ -0,0 +1,398 @@ +--- +title: Migration Guide +sidebar_order: 1000 +description: "Learn about migrating from io.sentry:sentry 1.x to io.sentry:sentry 3.x." +--- + +## Migrating from `io.sentry:sentry` `5.x` to `io.sentry:sentry` `6.0.0` + +* Kotlin plugin is upgraded to `1.5`. +* Kotlin `languageVersion` is upgraded to `1.4`. +* `Gson` is removed as a transitive dependency and vendored in the SDK. + * Protocol classes now implement the `JsonSerializable` and `JsonDeserializer` interfaces. +* Spring Boot has been upgraded to `2.5.13` +* `SentryOptions#shutdownTimeout` is renamed to `shutdownTimeoutMillis`. +* Removed `@Deprecated` and `@ApiStatus.ScheduledForRemoval` methods + * `ITransaction#setRequest` + * `ITransaction#getRequest` + * `ITransaction#getContexts` + * `SentryBaseEvent#getOriginThrowable` + * `SentryOptions#getCacheDirSize` + * `SentryOptions#setCacheDirSize` + * `SentryOptions#isEnableSessionTracking` + * `SentryOptions#setEnableSessionTracking` + * `sentry.enable-tracing` property + * `SentrySpringRequestListener`, `SentrySpringFilter` is used instead. + * `SentryUserProviderEventProcessor`, please use `SentryUserProvider` instead. +* `SentryOptions#enableScopeSync` is now enabled by default. +* `ISpan` now has higher precision using the `System#nanoTime` instead of milliseconds. +* `TransactionNameProvider` is now an interface and `SpringMvcTransactionNameProvider` is the default implementation. + +* Hints changed its type from `Object` to `io.sentry.Hint` + +_Old_: + +```kotlin +Sentry.captureException(RuntimeException("exception"), "myStringHint") +``` + +_New_: + +```kotlin +val hints = mutableMapOf("myHint" to "myStringHint") +Sentry.captureException(RuntimeException("exception"), hints) +``` + +* `SentryOptions#sendClientReports` is now enabled by default. To disable it, see [sendClientReports](/platforms/java/configuration/#client-reports). For more information on the option see [sendClientReports](/platforms/java/configuration/options/#send-client-reports). + +### Sentry Self-hosted Compatibility + +- Starting with version `6.0.0` of `sentry`, [Sentry's version >= v21.9.0](https://github.com/getsentry/self-hosted/releases) is required or you have to manually disable sending client reports via the `sendClientReports` option. This only applies to self-hosted Sentry. If you are using [sentry.io](https://sentry.io), no action is needed. + +There are more changes and refactors, but they are not user breaking changes. + +## Migrating from `io.sentry:sentry` `4.3.0` to `io.sentry:sentry` `5.0.0` + +`Sentry#startTransaction` by default does not bind created transaction to the scope. To start transaction with binding to the scope, use one of the new overloaded `startTransaction` methods taking `bindToScope` parameter and set it to `true`. Bound transaction can be retrieved with `Sentry#getSpan`. + +All SDK methods have been annotated with [JetBrains Annotations](https://github.com/JetBrains/java-annotations): `@Nullable` and `@NotNull`. Kotlin compiler respects these annotations and as a result, in Kotlin code, some fields that were recognized as not-null, are now nullable, and the other way around. + +`SentryBaseEvent#getOriginThrowable` has been deprecated in favor of `SentryBaseEvent#getThrowable`, and `SentryBaseEvent#getThrowable` now returns the unwrapped throwable. + +The `ShutdownHookIntegration` now flushes the SDK instead of closing it. + +`SentryOptions#getCacheDirSize` has been deprecated in favor of `SentryOptions#getMaxCacheItems`. + +`InvalidDsnException` has been removed. It is replaced by `IllegalArgumentException`. + +`EventProcessor` interface has a new `default` method which could break the instantiation when using trailing lambdas. + +_Old_: + +```kotlin +SentryOptions#addEventProcessor { event, _ -> event } +``` + +_New_: + +```kotlin +SentryOptions#addEventProcessor(object : EventProcessor { + override fun process(event: SentryEvent, hint: Hint): SentryEvent? { + return event + } +}) +``` + +### Spring Boot + +The property `sentry.enable-tracing` is deprecated. To enable tracing simply set `sentry.traces-sample-rate` or create a bean implementing `TracesSamplerCallback`. + +## Migrating from `io.sentry:sentry` `4.1.0` to `io.sentry:sentry` `4.2.0` + +`operation` is now a required property of the `SentryTransaction` and `SentrySpan`. Whenever a transaction or span is started, the value for `operation` must be provided: + +```java +Sentry.startTransaction("transaction-name", "operation-name"); +``` + +### Spring + +#### RestTemplate instrumentation + +Simplified `RestTemplate` instrumentation does not involve anymore setting `UriTemplateHandler` using `SentrySpanClientHttpRequestInterceptor`. + +Code snippet adding Sentry `RestTemplate` instrumentation changed from: + +```java +@Bean +RestTemplate restTemplate(IHub hub) { + RestTemplate restTemplate = new RestTemplate(); + SentrySpanClientHttpRequestInterceptor sentryRestTemplateInterceptor = new SentrySpanClientHttpRequestInterceptor(hub); + UriTemplateHandler templateHandler = restTemplate.getUriTemplateHandler(); + restTemplate.setUriTemplateHandler(sentryRestTemplateInterceptor.createUriTemplateHandler(templateHandler)); + restTemplate.setInterceptors(Collections.singletonList(sentryRestTemplateInterceptor)); + return restTemplate; +} +``` + +into: + +```java +@Bean +RestTemplate restTemplate(IHub hub) { + RestTemplate restTemplate = new RestTemplate(); + SentrySpanClientHttpRequestInterceptor sentryRestTemplateInterceptor = new SentrySpanClientHttpRequestInterceptor(hub); + restTemplate.setInterceptors(Collections.singletonList(sentryRestTemplateInterceptor)); + return restTemplate; +} +``` + +#### SentryExceptionResolver does not send handled errors by default + +To prevent `SentryExceptionResolver` from sending errors that have been already captured by `@ExceptionHandlers`, we've changed the order for `SentryExceptionResolver` to `1`. + +Old behavior can be brought back by setting `exceptionResolverOrder` property on `@EnableSentry`: + +```java +@EnableSentry(exceptionResolverOrder = -2147483648) +class CustomConfiguration { + ... +} +``` + +### Spring Boot + +#### SentryExceptionResolver does not send handled errors by default + +To prevent `SentryExceptionResolver` from sending errors that have been already captured by `@ExceptionHandlers`, we've changed the order for `SentryExceptionResolver` to `1`. + +Old behavior can be brought back by setting a property `sentry.exception-resolver-order=-2147483648` + +#### `@SentryTransaction` `operation` is now required + +`@SentryTransaction` must have `operation` property provided. + +```java +class MyComponent { + + @SentryTransaction(name = "transaction-name", operation = "operation-name") + @Scheduled(fixedRate = 3 * 1000L) + void execute() { + ... + } +} +``` + +## Migrating from `io.sentry:sentry` `1.x` to `io.sentry:sentry` `4.x` + + +Our update to the API follows the [Unified API](https://develop.sentry.dev/sdk/unified-api/) more closely. It's a completely updated code base, written to support our Android SDK. + +### API Changes + +#### Set tag + +_Previous_: + +```java +Sentry.getContext().addTag("tagName", "tagValue"); +``` + +```kotlin +Sentry.getContext().addTag("tagName", "tagValue") +``` + +_Updated_: + +```java +Sentry.setTag("tagName", "tagValue"); +``` + +```kotlin +Sentry.setTag("tagName", "tagValue") +``` + +#### Capture custom exception + +_Previous_: + +```java +try { + int x = 1 / 0; +} catch (Exception e) { + Sentry.capture(e); +} +``` + +```kotlin +try { + val x = 1 / 0 +} catch (e: Exception) { + Sentry.capture(e) +} +``` + +_New_: + +```java +try { + int x = 1 / 0; +} catch (Exception e) { + Sentry.captureException(e); +} +``` + +```kotlin +try { + val x = 1 / 0 +} catch (e: Exception) { + Sentry.captureException(e) +} +``` + +#### Capture a message + +_Previous_: + +```java +Sentry.capture("This is a test"); +``` + +```kotlin +Sentry.capture("This is a test") +``` + +_New_: + +```java +Sentry.captureMessage("This is a test"); // SentryLevel.INFO by default +Sentry.captureMessage("This is a test", SentryLevel.WARNING); // or specific level +``` + +```kotlin +Sentry.captureMessage("This is a test") // SentryLevel.INFO by default +Sentry.captureMessage("This is a test", SentryLevel.WARNING) // or specific level +``` + +#### Breadcrumbs + +_Previous_: + +```java +Sentry.getContext().recordBreadcrumb( + new BreadcrumbBuilder().setMessage("User made an action").build() +); +``` + +```kotlin +Sentry.getContext().recordBreadcrumb( + BreadcrumbBuilder().setMessage("User made an action").build() +) +``` + +_New_: + +```java +Sentry.addBreadcrumb("User made an action"); +``` + +```kotlin +Sentry.addBreadcrumb("User made an action") +``` + +#### User + +_Previous_: + +```java +Sentry.getContext().setUser( + new UserBuilder().setEmail("hello@sentry.io").build() +); +``` + +```kotlin +Sentry.getContext().setUser( + UserBuilder().setEmail("hello@sentry.io").build() +) +``` + +_New_: + +```java +User user = new User(); +user.setEmail("hello@sentry.io"); +Sentry.setUser(user); +``` + +```kotlin +val user = User().apply { + email = "hello@sentry.io" +} +Sentry.setUser(user) +``` + +#### Set extra + +_Previous_: + +```java +Sentry.getContext().addExtra("extra", "thing"); +``` + +```kotlin +Sentry.getContext().addExtra("extra", "thing") +``` + +_New_: + +```java +Sentry.setExtra("extra", "thing"); +``` + +```kotlin +Sentry.setExtra("extra", "thing") +``` + +### Removed Properties + +Following configuration properties have been removed: + +- `buffer.dir` - can be set with `SentryOptions#cacheDirPath` +- `buffer.size` - can be set with `SentryOptions#cacheDirSize` +- `buffer.flushtime` - can be set with `SentryOptions#flushTimeoutMillis` +- `buffer.shutdowntimeout` +- `buffer.gracefulshutdown` +- `async` +- `async.shutdowntimeout` - can be set with `SentryOptions#shutdownTimeout` +- `async.gracefulshutdown` +- `async.queuesize` - can be set with `SentryOptions#maxQueueSize` +- `async.threads` +- `async.priority` +- `compression` +- `maxmessagelength` +- `factory` +- `mdcTags` +- `extra` - can be set on the scope with `Scope#extra` + + +### Property Name Changes + +Following properties cannot be set anymore through external configuration and have to be set directly on `SentryOptions` object when initializing Sentry: + +- `sample.rate` - through `SentryOptions#sampleRate` +- `timeout` - through `SentryOptions#connectionTimeoutMillis` and `SentryOptions#readTimeoutMillis` + +See Configuration page to find all available configuration properties. + +#### Tags + +_Previous_: + +```properties +tags=tag1:value1,tag2:value2 +``` + +_New_: + +```properties +tags.tag1=value1 +tags.tag2=value2 +``` + +#### “In Application” Stack Frames + +```java +stacktrace.app.packages=com.mycompany,com.other.name +``` + +_New_: + +```properties +in-app-includes=com.mycompany,com.other.name +``` + +There is also an option to exclude certain packages from stacktraces: + +```properties +in-app-excludes=com.packages.to.exclude +``` From f0c3e9d8d11ddd71e52efa32d508aa85bff386ee Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Fri, 10 Mar 2023 10:58:07 +0100 Subject: [PATCH 02/11] add init strategies & improve docs --- .../config-intro/kotlin-multiplatform.mdx | 5 +- .../add-attachment/kotlin-multiplatform.mdx | 1 - .../kotlin-multiplatform.mdx | 1 - .../kotlin-multiplatform.mdx | 8 + .../kotlin-multiplatform.mdx | 16 +- .../kotlin-multiplatform.mdx | 2 - .../set-user/kotlin-multiplatform.mdx | 10 +- .../kotlin-multiplatform.mdx | 10 +- .../kotlin-multiplatform.mdx | 20 +- .../kotlin-multiplatform.mdx | 2 +- .../set-environment/kotlin-multiplatform.mdx | 2 +- .../set-release/kotlin-multiplatform.mdx | 3 +- .../common/enriching-events/breadcrumbs.mdx | 2 +- .../common/enriching-events/scopes.mdx | 4 +- .../common/enriching-events/user-feedback.mdx | 2 +- src/platforms/kotlin-multiplatform/config.yml | 2 +- .../initialization-strategies.mdx | 102 +++++ .../kotlin-multiplatform/migration.mdx | 398 ------------------ 18 files changed, 160 insertions(+), 430 deletions(-) create mode 100644 src/platform-includes/enriching-events/attachment-max-size/kotlin-multiplatform.mdx create mode 100644 src/platforms/kotlin-multiplatform/initialization-strategies.mdx delete mode 100644 src/platforms/kotlin-multiplatform/migration.mdx diff --git a/src/platform-includes/configuration/config-intro/kotlin-multiplatform.mdx b/src/platform-includes/configuration/config-intro/kotlin-multiplatform.mdx index f7b418ce83ba7..0c44fb46eeb92 100644 --- a/src/platform-includes/configuration/config-intro/kotlin-multiplatform.mdx +++ b/src/platform-includes/configuration/config-intro/kotlin-multiplatform.mdx @@ -1,10 +1,7 @@ - - If Android is a target in your application, the application context is needed for initialization. - - ```kotlin import io.sentry.kotlin.multiplatform.Sentry +// Application context is only needed for Android targets Sentry.init(context) { options -> options.dsn = "___PUBLIC_DSN___" options.release = "io.sentry.samples@3.0.0+1" diff --git a/src/platform-includes/enriching-events/add-attachment/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/add-attachment/kotlin-multiplatform.mdx index d68507e4b9ea0..95e2c1fe8dbd0 100644 --- a/src/platform-includes/enriching-events/add-attachment/kotlin-multiplatform.mdx +++ b/src/platform-includes/enriching-events/add-attachment/kotlin-multiplatform.mdx @@ -14,4 +14,3 @@ Sentry.captureException(IllegalStateException()) { scope -> scope.addAttachment(fileAttachment) } ``` -// TODO: max attachment size diff --git a/src/platform-includes/enriching-events/attachment-init-with-bytes/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/attachment-init-with-bytes/kotlin-multiplatform.mdx index 095a176f61c41..2bbbfc4c44972 100644 --- a/src/platform-includes/enriching-events/attachment-init-with-bytes/kotlin-multiplatform.mdx +++ b/src/platform-includes/enriching-events/attachment-init-with-bytes/kotlin-multiplatform.mdx @@ -4,4 +4,3 @@ import io.sentry.kotlin.multiplatform.Attachment val attachment = Attachment(bytes, "file.log") ``` -// TODO: byte attachment diff --git a/src/platform-includes/enriching-events/attachment-max-size/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/attachment-max-size/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..47fb384d49cd8 --- /dev/null +++ b/src/platform-includes/enriching-events/attachment-max-size/kotlin-multiplatform.mdx @@ -0,0 +1,8 @@ +```kotlin +import io.sentry.kotlin.multiplatform.Sentry + +// Application context is only needed for Android targets +Sentry.init(context) { options -> + options.maxAttachmentSize = 5 * 1024 * 1024 // 5 MiB +} +``` diff --git a/src/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/kotlin-multiplatform.mdx index d066a7aa19a0d..ccaa00c9a8912 100644 --- a/src/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/kotlin-multiplatform.mdx +++ b/src/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/kotlin-multiplatform.mdx @@ -1,14 +1,15 @@ ```kotlin import io.sentry.kotlin.multiplatform.Sentry -Sentry.init { options -> - options.beforeBreadcrumb = { breadcrumb -> - breadcrumb.apply { - if (this.category == "navigation") { - this.message = "Add message to navigation breadcrumb" - } - } +// Application context is only needed for Android targets +Sentry.init(context) { options -> + options.beforeBreadcrumb = { breadcrumb -> + if ("a.spammy.Logger" == breadcrumb.category) { + null + } else { + breadcrumb } + } } ``` @@ -35,4 +36,3 @@ If you want to disable the automatic collection of breadcrumbs on Android, pleas ``` -// TODO: cant drop breadcrumbs diff --git a/src/platform-includes/enriching-events/breadcrumbs/breadcrumbs-example/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/breadcrumbs/breadcrumbs-example/kotlin-multiplatform.mdx index 596b402dff5c9..49a0f64f433a2 100644 --- a/src/platform-includes/enriching-events/breadcrumbs/breadcrumbs-example/kotlin-multiplatform.mdx +++ b/src/platform-includes/enriching-events/breadcrumbs/breadcrumbs-example/kotlin-multiplatform.mdx @@ -10,5 +10,3 @@ val breadcrumb = Breadcrumb().apply { } Sentry.addBreadcrumb(breadcrumb) ``` - -// TODO: addBreadcrumb diff --git a/src/platform-includes/enriching-events/set-user/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/set-user/kotlin-multiplatform.mdx index a188bb0f5ab1f..2ec9681c0edf1 100644 --- a/src/platform-includes/enriching-events/set-user/kotlin-multiplatform.mdx +++ b/src/platform-includes/enriching-events/set-user/kotlin-multiplatform.mdx @@ -1 +1,9 @@ -// TODO: setUser +```kotlin +import io.sentry.kotlin.multiplatform.Sentry +import io.sentry.kotlin.multiplatform.protocol.User + +val user = User().apply { + email = "jane.doe@example.com" +} +Sentry.setUser(user) +``` diff --git a/src/platform-includes/getting-started-config/kotlin-multiplatform.mdx b/src/platform-includes/getting-started-config/kotlin-multiplatform.mdx index cef309305ef2c..bcfe72a22dd18 100644 --- a/src/platform-includes/getting-started-config/kotlin-multiplatform.mdx +++ b/src/platform-includes/getting-started-config/kotlin-multiplatform.mdx @@ -1,11 +1,9 @@ ```kotlin -import io.sentry.kotlin.multiplatform.Context import io.sentry.kotlin.multiplatform.Sentry -// The context is needed for Android initializations -fun initializeSentry(context: Context?) { - Sentry.init(context) { - it.dsn = "___PUBLIC_DSN___" - } +// Application context is only needed for Android targets +Sentry.init(context) { -> + options.dsn = "___PUBLIC_DSN___" + options.release = "io.sentry.samples@3.0.0+1" } ``` diff --git a/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx b/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx index 478f2e2466d70..a46f5fb57324b 100644 --- a/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx +++ b/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx @@ -1,3 +1,12 @@ +### Prerequisites (Android) +Android require disabling auto-init on Android to not clash with the ContentProvider, which auto-initializes the Sentry Android SDK. To do so, add the following to the AndroidManifest.xml file under your androidMain source set: + +```kotlin + + + +``` + To install the Kotlin Multiplatform SDK, you need to add the following to your `build.gradle.kts` file in your shared module: ```kotlin {filename:build.gradle.kt} @@ -12,7 +21,16 @@ kotlin { } } - // If you target Apple platforms: + // Android target + val androidMain by getting { + dependsOn(commonMain) + } + + // Apple targets: + val iosMain by getting { + dependsOn(commonMain) + } + cocoapods { summary = "Some description for the Shared Module" homepage = "Link to the Shared Module homepage" diff --git a/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx b/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx index 284b33d673765..21d7b2cf16efa 100644 --- a/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx +++ b/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx @@ -2,4 +2,4 @@ - Native crash reporting for Android and JVM, leveraging our [Android SDK](/platforms/android) and [Java SDK](/platforms/java) - Native crash reporting for iOS and macOS, tvOS, watchOS, leveraging our [Cocoa SDK](/platforms/apple) -- Automatic breadcrumbs for native Android and Cocoa app lifecycle and UI events +- Automatic breadcrumbs for app lifecycle and UI events diff --git a/src/platform-includes/set-environment/kotlin-multiplatform.mdx b/src/platform-includes/set-environment/kotlin-multiplatform.mdx index 1fbbd63783e7b..0298e873b4ea3 100644 --- a/src/platform-includes/set-environment/kotlin-multiplatform.mdx +++ b/src/platform-includes/set-environment/kotlin-multiplatform.mdx @@ -1,7 +1,7 @@ ```kotlin import io.sentry.kotlin.multiplatform.Sentry -// Context is only needed if you are targeting Android as well +// Application context is only needed for Android targets Sentry.init(context) { it.environment = "production" } diff --git a/src/platform-includes/set-release/kotlin-multiplatform.mdx b/src/platform-includes/set-release/kotlin-multiplatform.mdx index 2e7a61ac26cf8..97e2cba2a5d41 100644 --- a/src/platform-includes/set-release/kotlin-multiplatform.mdx +++ b/src/platform-includes/set-release/kotlin-multiplatform.mdx @@ -1,7 +1,8 @@ ```kotlin import io.sentry.kotlin.multiplatform.Sentry -Sentry.init(androidContext) { options -> +// Application context is only needed for Android targets +Sentry.init(context) { options -> options.release = "io.example@1.1.0" } ``` diff --git a/src/platforms/common/enriching-events/breadcrumbs.mdx b/src/platforms/common/enriching-events/breadcrumbs.mdx index 9eb54e545df48..cd41cc2fc57bb 100644 --- a/src/platforms/common/enriching-events/breadcrumbs.mdx +++ b/src/platforms/common/enriching-events/breadcrumbs.mdx @@ -71,7 +71,7 @@ This hook is passed an already assembled breadcrumb and, in some SDKs, an option - + For information about what can be done with the hint, see Filtering Events. diff --git a/src/platforms/common/enriching-events/scopes.mdx b/src/platforms/common/enriching-events/scopes.mdx index ae1b0cebe26d8..8bf38635040e5 100644 --- a/src/platforms/common/enriching-events/scopes.mdx +++ b/src/platforms/common/enriching-events/scopes.mdx @@ -111,7 +111,7 @@ We also support pushing and configuring a scope within a single call. This is ty called `with-scope`, `push-scope` or implemented as a function parameter on the capture methods, depending on the SDK. It's very helpful if you only want to send data for one specific event. - + ### Using `with-scope` @@ -165,7 +165,7 @@ caught, and all errors that occur will be silently ignored and **not** reported. - + ## Kotlin Coroutines diff --git a/src/platforms/common/enriching-events/user-feedback.mdx b/src/platforms/common/enriching-events/user-feedback.mdx index a9aeb9937d9e8..e0591c8f05637 100644 --- a/src/platforms/common/enriching-events/user-feedback.mdx +++ b/src/platforms/common/enriching-events/user-feedback.mdx @@ -26,7 +26,7 @@ While this feature isn't currently supported for Ruby or most of its frameworks, The user feedback API provides the ability to collect user information when an event occurs. You can use the same programming language you have in your app to send user feedback. In this case, the SDK creates the HTTP request so you don't have to deal with posting data via HTTP. - + Sentry pairs the feedback with the original event, giving you additional insight into issues. Sentry needs the `eventId` to be able to associate the user feedback to the corresponding event. For example, to get the `eventId`, you can use or the return value of the method capturing an event. diff --git a/src/platforms/kotlin-multiplatform/config.yml b/src/platforms/kotlin-multiplatform/config.yml index 8e44c8c28ab62..d42c93c517a20 100644 --- a/src/platforms/kotlin-multiplatform/config.yml +++ b/src/platforms/kotlin-multiplatform/config.yml @@ -1,8 +1,8 @@ title: Kotlin Multiplatform caseStyle: camelCase +fallbackPlatform: java supportLevel: production sdk: sentry.kotlin.kmp -fallbackPlatform: java categories: - mobile - desktop diff --git a/src/platforms/kotlin-multiplatform/initialization-strategies.mdx b/src/platforms/kotlin-multiplatform/initialization-strategies.mdx new file mode 100644 index 0000000000000..3bc131d665c13 --- /dev/null +++ b/src/platforms/kotlin-multiplatform/initialization-strategies.mdx @@ -0,0 +1,102 @@ +--- +title: Initialization Strategies +sidebar_order: 0 +description: "Different strategies how to initialize the Kotlin Multiplatform SDK." +--- + +When it comes to initializing a Kotlin Multiplatform SDK, there are three strategies to consider: + - [Shared initializer](#shared-initializer) + - [Platform specific initializers](#platform-specific-initializers) + - [Hybrid approach](#hybrid-approach) + +## Shared initializer + +The shared initializer approach involves initializing the SDK in your shared codebase, using the same configuration options for all platforms. This approach is ideal for projects that prioritize consistency across platforms and do not require platform-specific customizations. + +Using a shared initializer provides a single source of truth for your SDK's configuration options. This can simplify maintenance and debugging efforts, as you only need to update one codebase for all platforms. + +Inside a Kotlin file in your commonMain e.g. `AppSetup.kt` or however you want to call it and create a function that will initialize the SDK. +Afterwards you can call it in an early lifecycle stage in your platforms. + +```kotlin {filename:AppSetup.kt} +import io.sentry.kotlin.multiplatform.Context +import io.sentry.kotlin.multiplatform.Sentry + +// Application context is only needed for Android targets +fun initializeSentry(context: Context?) { + Sentry.init(context) { + it.dsn = "___PUBLIC_DSN___" + } +} +``` + +### Android + +```kotlin {filename:MainActivity.kt} +import your.kmp.app.initializeSentry + +class YourApplication : Application() { + override fun onCreate() { + super.onCreate() + // Make sure to add the context! + initializeSentry(this) + } +} +``` + +### Cocoa/Apple + +```swift {filename:AppDelegate.swift} +import shared + +func application( + _ application: UIApplication, + didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil +) -> Bool { + AppSetupKt.initializeSentry(context = nil) + return true +} +``` + +## Platform specific initializers + +Platform specific initializers allow for customization of the SDK's configuration options on a per-platform basis. This approach can be particularly useful when your SDK requires platform specific functionality or performance optimizations. + +With platform-specific initializers, you can initialize the SDK directly in the target platform's codebase. This approach gives you the flexibility to fine-tune the SDK's behavior to meet the unique needs of each platform. + +### Android +```kotlin {filename:MainActivity.kt} +import io.sentry.kotlin.multiplatform.Sentry + +class YourApplication : Application() { + override fun onCreate() { + super.onCreate() + // Make sure to add the context! + Sentry.init(this) { + it.dsn = "___PUBLIC_DSN___" + } + } +} +``` + +### Cocoa/Apple + +```swift {filename:AppDelegate.swift} +import shared + +func application( + _ application: UIApplication, + didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil +) -> Bool { + Sentry.shared.doInit() { options in + options.dsn = "___PUBLIC_DSN___" + } + return true +} +``` + +## Hybrid approach + +It is also possible to mix the two initialization strategies by creating custom sourcesets that only target specific platforms. This allows you to use a shared initializer for some platforms while utilizing platform-specific initializers for others. + +For example, you may choose to use a shared initializer for Android and iOS platforms while using a platform specific initializer for the watchOS and tvOS platform. This approach provides a balance between consistency and customization. diff --git a/src/platforms/kotlin-multiplatform/migration.mdx b/src/platforms/kotlin-multiplatform/migration.mdx deleted file mode 100644 index 8a6b321307644..0000000000000 --- a/src/platforms/kotlin-multiplatform/migration.mdx +++ /dev/null @@ -1,398 +0,0 @@ ---- -title: Migration Guide -sidebar_order: 1000 -description: "Learn about migrating from io.sentry:sentry 1.x to io.sentry:sentry 3.x." ---- - -## Migrating from `io.sentry:sentry` `5.x` to `io.sentry:sentry` `6.0.0` - -* Kotlin plugin is upgraded to `1.5`. -* Kotlin `languageVersion` is upgraded to `1.4`. -* `Gson` is removed as a transitive dependency and vendored in the SDK. - * Protocol classes now implement the `JsonSerializable` and `JsonDeserializer` interfaces. -* Spring Boot has been upgraded to `2.5.13` -* `SentryOptions#shutdownTimeout` is renamed to `shutdownTimeoutMillis`. -* Removed `@Deprecated` and `@ApiStatus.ScheduledForRemoval` methods - * `ITransaction#setRequest` - * `ITransaction#getRequest` - * `ITransaction#getContexts` - * `SentryBaseEvent#getOriginThrowable` - * `SentryOptions#getCacheDirSize` - * `SentryOptions#setCacheDirSize` - * `SentryOptions#isEnableSessionTracking` - * `SentryOptions#setEnableSessionTracking` - * `sentry.enable-tracing` property - * `SentrySpringRequestListener`, `SentrySpringFilter` is used instead. - * `SentryUserProviderEventProcessor`, please use `SentryUserProvider` instead. -* `SentryOptions#enableScopeSync` is now enabled by default. -* `ISpan` now has higher precision using the `System#nanoTime` instead of milliseconds. -* `TransactionNameProvider` is now an interface and `SpringMvcTransactionNameProvider` is the default implementation. - -* Hints changed its type from `Object` to `io.sentry.Hint` - -_Old_: - -```kotlin -Sentry.captureException(RuntimeException("exception"), "myStringHint") -``` - -_New_: - -```kotlin -val hints = mutableMapOf("myHint" to "myStringHint") -Sentry.captureException(RuntimeException("exception"), hints) -``` - -* `SentryOptions#sendClientReports` is now enabled by default. To disable it, see [sendClientReports](/platforms/java/configuration/#client-reports). For more information on the option see [sendClientReports](/platforms/java/configuration/options/#send-client-reports). - -### Sentry Self-hosted Compatibility - -- Starting with version `6.0.0` of `sentry`, [Sentry's version >= v21.9.0](https://github.com/getsentry/self-hosted/releases) is required or you have to manually disable sending client reports via the `sendClientReports` option. This only applies to self-hosted Sentry. If you are using [sentry.io](https://sentry.io), no action is needed. - -There are more changes and refactors, but they are not user breaking changes. - -## Migrating from `io.sentry:sentry` `4.3.0` to `io.sentry:sentry` `5.0.0` - -`Sentry#startTransaction` by default does not bind created transaction to the scope. To start transaction with binding to the scope, use one of the new overloaded `startTransaction` methods taking `bindToScope` parameter and set it to `true`. Bound transaction can be retrieved with `Sentry#getSpan`. - -All SDK methods have been annotated with [JetBrains Annotations](https://github.com/JetBrains/java-annotations): `@Nullable` and `@NotNull`. Kotlin compiler respects these annotations and as a result, in Kotlin code, some fields that were recognized as not-null, are now nullable, and the other way around. - -`SentryBaseEvent#getOriginThrowable` has been deprecated in favor of `SentryBaseEvent#getThrowable`, and `SentryBaseEvent#getThrowable` now returns the unwrapped throwable. - -The `ShutdownHookIntegration` now flushes the SDK instead of closing it. - -`SentryOptions#getCacheDirSize` has been deprecated in favor of `SentryOptions#getMaxCacheItems`. - -`InvalidDsnException` has been removed. It is replaced by `IllegalArgumentException`. - -`EventProcessor` interface has a new `default` method which could break the instantiation when using trailing lambdas. - -_Old_: - -```kotlin -SentryOptions#addEventProcessor { event, _ -> event } -``` - -_New_: - -```kotlin -SentryOptions#addEventProcessor(object : EventProcessor { - override fun process(event: SentryEvent, hint: Hint): SentryEvent? { - return event - } -}) -``` - -### Spring Boot - -The property `sentry.enable-tracing` is deprecated. To enable tracing simply set `sentry.traces-sample-rate` or create a bean implementing `TracesSamplerCallback`. - -## Migrating from `io.sentry:sentry` `4.1.0` to `io.sentry:sentry` `4.2.0` - -`operation` is now a required property of the `SentryTransaction` and `SentrySpan`. Whenever a transaction or span is started, the value for `operation` must be provided: - -```java -Sentry.startTransaction("transaction-name", "operation-name"); -``` - -### Spring - -#### RestTemplate instrumentation - -Simplified `RestTemplate` instrumentation does not involve anymore setting `UriTemplateHandler` using `SentrySpanClientHttpRequestInterceptor`. - -Code snippet adding Sentry `RestTemplate` instrumentation changed from: - -```java -@Bean -RestTemplate restTemplate(IHub hub) { - RestTemplate restTemplate = new RestTemplate(); - SentrySpanClientHttpRequestInterceptor sentryRestTemplateInterceptor = new SentrySpanClientHttpRequestInterceptor(hub); - UriTemplateHandler templateHandler = restTemplate.getUriTemplateHandler(); - restTemplate.setUriTemplateHandler(sentryRestTemplateInterceptor.createUriTemplateHandler(templateHandler)); - restTemplate.setInterceptors(Collections.singletonList(sentryRestTemplateInterceptor)); - return restTemplate; -} -``` - -into: - -```java -@Bean -RestTemplate restTemplate(IHub hub) { - RestTemplate restTemplate = new RestTemplate(); - SentrySpanClientHttpRequestInterceptor sentryRestTemplateInterceptor = new SentrySpanClientHttpRequestInterceptor(hub); - restTemplate.setInterceptors(Collections.singletonList(sentryRestTemplateInterceptor)); - return restTemplate; -} -``` - -#### SentryExceptionResolver does not send handled errors by default - -To prevent `SentryExceptionResolver` from sending errors that have been already captured by `@ExceptionHandlers`, we've changed the order for `SentryExceptionResolver` to `1`. - -Old behavior can be brought back by setting `exceptionResolverOrder` property on `@EnableSentry`: - -```java -@EnableSentry(exceptionResolverOrder = -2147483648) -class CustomConfiguration { - ... -} -``` - -### Spring Boot - -#### SentryExceptionResolver does not send handled errors by default - -To prevent `SentryExceptionResolver` from sending errors that have been already captured by `@ExceptionHandlers`, we've changed the order for `SentryExceptionResolver` to `1`. - -Old behavior can be brought back by setting a property `sentry.exception-resolver-order=-2147483648` - -#### `@SentryTransaction` `operation` is now required - -`@SentryTransaction` must have `operation` property provided. - -```java -class MyComponent { - - @SentryTransaction(name = "transaction-name", operation = "operation-name") - @Scheduled(fixedRate = 3 * 1000L) - void execute() { - ... - } -} -``` - -## Migrating from `io.sentry:sentry` `1.x` to `io.sentry:sentry` `4.x` - - -Our update to the API follows the [Unified API](https://develop.sentry.dev/sdk/unified-api/) more closely. It's a completely updated code base, written to support our Android SDK. - -### API Changes - -#### Set tag - -_Previous_: - -```java -Sentry.getContext().addTag("tagName", "tagValue"); -``` - -```kotlin -Sentry.getContext().addTag("tagName", "tagValue") -``` - -_Updated_: - -```java -Sentry.setTag("tagName", "tagValue"); -``` - -```kotlin -Sentry.setTag("tagName", "tagValue") -``` - -#### Capture custom exception - -_Previous_: - -```java -try { - int x = 1 / 0; -} catch (Exception e) { - Sentry.capture(e); -} -``` - -```kotlin -try { - val x = 1 / 0 -} catch (e: Exception) { - Sentry.capture(e) -} -``` - -_New_: - -```java -try { - int x = 1 / 0; -} catch (Exception e) { - Sentry.captureException(e); -} -``` - -```kotlin -try { - val x = 1 / 0 -} catch (e: Exception) { - Sentry.captureException(e) -} -``` - -#### Capture a message - -_Previous_: - -```java -Sentry.capture("This is a test"); -``` - -```kotlin -Sentry.capture("This is a test") -``` - -_New_: - -```java -Sentry.captureMessage("This is a test"); // SentryLevel.INFO by default -Sentry.captureMessage("This is a test", SentryLevel.WARNING); // or specific level -``` - -```kotlin -Sentry.captureMessage("This is a test") // SentryLevel.INFO by default -Sentry.captureMessage("This is a test", SentryLevel.WARNING) // or specific level -``` - -#### Breadcrumbs - -_Previous_: - -```java -Sentry.getContext().recordBreadcrumb( - new BreadcrumbBuilder().setMessage("User made an action").build() -); -``` - -```kotlin -Sentry.getContext().recordBreadcrumb( - BreadcrumbBuilder().setMessage("User made an action").build() -) -``` - -_New_: - -```java -Sentry.addBreadcrumb("User made an action"); -``` - -```kotlin -Sentry.addBreadcrumb("User made an action") -``` - -#### User - -_Previous_: - -```java -Sentry.getContext().setUser( - new UserBuilder().setEmail("hello@sentry.io").build() -); -``` - -```kotlin -Sentry.getContext().setUser( - UserBuilder().setEmail("hello@sentry.io").build() -) -``` - -_New_: - -```java -User user = new User(); -user.setEmail("hello@sentry.io"); -Sentry.setUser(user); -``` - -```kotlin -val user = User().apply { - email = "hello@sentry.io" -} -Sentry.setUser(user) -``` - -#### Set extra - -_Previous_: - -```java -Sentry.getContext().addExtra("extra", "thing"); -``` - -```kotlin -Sentry.getContext().addExtra("extra", "thing") -``` - -_New_: - -```java -Sentry.setExtra("extra", "thing"); -``` - -```kotlin -Sentry.setExtra("extra", "thing") -``` - -### Removed Properties - -Following configuration properties have been removed: - -- `buffer.dir` - can be set with `SentryOptions#cacheDirPath` -- `buffer.size` - can be set with `SentryOptions#cacheDirSize` -- `buffer.flushtime` - can be set with `SentryOptions#flushTimeoutMillis` -- `buffer.shutdowntimeout` -- `buffer.gracefulshutdown` -- `async` -- `async.shutdowntimeout` - can be set with `SentryOptions#shutdownTimeout` -- `async.gracefulshutdown` -- `async.queuesize` - can be set with `SentryOptions#maxQueueSize` -- `async.threads` -- `async.priority` -- `compression` -- `maxmessagelength` -- `factory` -- `mdcTags` -- `extra` - can be set on the scope with `Scope#extra` - - -### Property Name Changes - -Following properties cannot be set anymore through external configuration and have to be set directly on `SentryOptions` object when initializing Sentry: - -- `sample.rate` - through `SentryOptions#sampleRate` -- `timeout` - through `SentryOptions#connectionTimeoutMillis` and `SentryOptions#readTimeoutMillis` - -See Configuration page to find all available configuration properties. - -#### Tags - -_Previous_: - -```properties -tags=tag1:value1,tag2:value2 -``` - -_New_: - -```properties -tags.tag1=value1 -tags.tag2=value2 -``` - -#### “In Application” Stack Frames - -```java -stacktrace.app.packages=com.mycompany,com.other.name -``` - -_New_: - -```properties -in-app-includes=com.mycompany,com.other.name -``` - -There is also an option to exclude certain packages from stacktraces: - -```properties -in-app-excludes=com.packages.to.exclude -``` From 70f81fc483ac8ac3c0dbca299da374f456076733 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Fri, 10 Mar 2023 11:06:33 +0100 Subject: [PATCH 03/11] add comment to init and remove android description --- .../kotlin-multiplatform.mdx | 3 ++- .../kotlin-multiplatform.mdx | 24 ------------------- .../unset-user/kotlin-multiplatform.mdx | 2 +- 3 files changed, 3 insertions(+), 26 deletions(-) diff --git a/src/platform-includes/enriching-events/attach-screenshots/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/attach-screenshots/kotlin-multiplatform.mdx index 848257ffd2972..0a981315c999e 100644 --- a/src/platform-includes/enriching-events/attach-screenshots/kotlin-multiplatform.mdx +++ b/src/platform-includes/enriching-events/attach-screenshots/kotlin-multiplatform.mdx @@ -1,7 +1,8 @@ ```kotlin import io.sentry.kotlin.multiplatform.Sentry -Sentry.init { options -> +// Application context is only needed for Android targets +Sentry.init(context) { options -> options.attachScreenshot = true } ``` diff --git a/src/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/kotlin-multiplatform.mdx index ccaa00c9a8912..52f060b42d0ae 100644 --- a/src/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/kotlin-multiplatform.mdx +++ b/src/platform-includes/enriching-events/breadcrumbs/before-breadcrumb/kotlin-multiplatform.mdx @@ -12,27 +12,3 @@ Sentry.init(context) { options -> } } ``` - -## Android -### Disable Automatic Breadcrumbs - -If you want to disable the automatic collection of breadcrumbs on Android, please add the following items into your manifest. - -```xml - - - - - - - - - - - - - - - - -``` diff --git a/src/platform-includes/enriching-events/unset-user/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/unset-user/kotlin-multiplatform.mdx index dc799f119d629..7f68baea82f37 100644 --- a/src/platform-includes/enriching-events/unset-user/kotlin-multiplatform.mdx +++ b/src/platform-includes/enriching-events/unset-user/kotlin-multiplatform.mdx @@ -1,4 +1,4 @@ -```kotlin {tabTitle: Kotlin} +```kotlin import io.sentry.kotlin.multiplatform.Sentry Sentry.configureScope { scope -> From e91ad115061085685c14d1e835684d829c81ae58 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Fri, 10 Mar 2023 12:26:09 +0100 Subject: [PATCH 04/11] review improvements --- .../getting-started-config/kotlin-multiplatform.mdx | 1 - .../getting-started-install/kotlin-multiplatform.mdx | 1 + .../getting-started-verify/kotlin-multiplatform.mdx | 2 ++ .../kotlin-multiplatform/initialization-strategies.mdx | 1 + 4 files changed, 4 insertions(+), 1 deletion(-) diff --git a/src/platform-includes/getting-started-config/kotlin-multiplatform.mdx b/src/platform-includes/getting-started-config/kotlin-multiplatform.mdx index bcfe72a22dd18..5c4eef9257114 100644 --- a/src/platform-includes/getting-started-config/kotlin-multiplatform.mdx +++ b/src/platform-includes/getting-started-config/kotlin-multiplatform.mdx @@ -4,6 +4,5 @@ import io.sentry.kotlin.multiplatform.Sentry // Application context is only needed for Android targets Sentry.init(context) { -> options.dsn = "___PUBLIC_DSN___" - options.release = "io.sentry.samples@3.0.0+1" } ``` diff --git a/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx b/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx index a46f5fb57324b..7f8d5e6194b8a 100644 --- a/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx +++ b/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx @@ -1,4 +1,5 @@ ### Prerequisites (Android) + Android require disabling auto-init on Android to not clash with the ContentProvider, which auto-initializes the Sentry Android SDK. To do so, add the following to the AndroidManifest.xml file under your androidMain source set: ```kotlin diff --git a/src/platform-includes/getting-started-verify/kotlin-multiplatform.mdx b/src/platform-includes/getting-started-verify/kotlin-multiplatform.mdx index 4d2a1a1f3a241..42dc9b122bae6 100644 --- a/src/platform-includes/getting-started-verify/kotlin-multiplatform.mdx +++ b/src/platform-includes/getting-started-verify/kotlin-multiplatform.mdx @@ -1,4 +1,6 @@ ```kotlin +import io.sentry.kotlin.multiplatform.Sentry + fun captureError() { try { throw Exception("This is a test.") diff --git a/src/platforms/kotlin-multiplatform/initialization-strategies.mdx b/src/platforms/kotlin-multiplatform/initialization-strategies.mdx index 3bc131d665c13..efb6aaaf0cd4f 100644 --- a/src/platforms/kotlin-multiplatform/initialization-strategies.mdx +++ b/src/platforms/kotlin-multiplatform/initialization-strategies.mdx @@ -65,6 +65,7 @@ Platform specific initializers allow for customization of the SDK's configuratio With platform-specific initializers, you can initialize the SDK directly in the target platform's codebase. This approach gives you the flexibility to fine-tune the SDK's behavior to meet the unique needs of each platform. ### Android + ```kotlin {filename:MainActivity.kt} import io.sentry.kotlin.multiplatform.Sentry From b0d54e04a1aefb441931f1d01f5600a7b95c1209 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Fri, 10 Mar 2023 14:33:51 +0100 Subject: [PATCH 05/11] add viewhierarchy --- .../attach-viewhierarchy/kotlin-multiplatform.mdx | 15 +++++++++++++++ .../common/enriching-events/viewhierarchy.mdx | 1 + 2 files changed, 16 insertions(+) create mode 100644 src/platform-includes/enriching-events/attach-viewhierarchy/kotlin-multiplatform.mdx diff --git a/src/platform-includes/enriching-events/attach-viewhierarchy/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/attach-viewhierarchy/kotlin-multiplatform.mdx new file mode 100644 index 0000000000000..6126fd6ad8d6b --- /dev/null +++ b/src/platform-includes/enriching-events/attach-viewhierarchy/kotlin-multiplatform.mdx @@ -0,0 +1,15 @@ + + +Currently only available on iOS and Android. + + + +```kotlin +import io.sentry.kotlin.multiplatform.sentry + +// Application context is only needed for Android targets +Sentry.init(context) { options -> + options.dsn = "___PUBLIC_DSN___" + options.attachViewHierarchy = true +} +``` diff --git a/src/platforms/common/enriching-events/viewhierarchy.mdx b/src/platforms/common/enriching-events/viewhierarchy.mdx index 7e5ea268c976a..42b9e20a0693e 100644 --- a/src/platforms/common/enriching-events/viewhierarchy.mdx +++ b/src/platforms/common/enriching-events/viewhierarchy.mdx @@ -7,6 +7,7 @@ supported: - flutter - android - react-native + - kotlin-multiplatform notSupported: - apple.macos - apple.tvos From 90e8b7a8f9206fae79794ac959e9fc5ead3d99d4 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Wed, 15 Mar 2023 14:48:14 +0100 Subject: [PATCH 06/11] doc review --- .../getting-started-install/kotlin-multiplatform.mdx | 6 +++--- .../getting-started-primer/kotlin-multiplatform.mdx | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx b/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx index 7f8d5e6194b8a..e3a9e4a110f8b 100644 --- a/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx +++ b/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx @@ -2,7 +2,7 @@ Android require disabling auto-init on Android to not clash with the ContentProvider, which auto-initializes the Sentry Android SDK. To do so, add the following to the AndroidManifest.xml file under your androidMain source set: -```kotlin +```xml @@ -18,7 +18,7 @@ repositories { kotlin { val commonMain by getting { dependencies { - api("io.sentry:sentry-kotlin-multiplatform:{{ packages.version('sentry.kotlin.kmp', '0.0.1') }}") + api("io.sentry:sentry-kotlin-multiplatform:{{ packages.version('sentry.kotlin.kmp', '0.0.1-alpha.2') }}") } } @@ -41,7 +41,7 @@ kotlin { framework { baseName = "shared" - export("io.sentry:sentry-kotlin-multiplatform:{{ packages.version('sentry.kotlin.kmp', '0.0.1') }}") + export("io.sentry:sentry-kotlin-multiplatform:{{ packages.version('sentry.kotlin.kmp', '0.0.1-alpha.2') }}") } } ``` diff --git a/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx b/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx index 21d7b2cf16efa..3cc6289f90210 100644 --- a/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx +++ b/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx @@ -1,5 +1,5 @@ -## Overview of the features +## Overview of features - Native crash reporting for Android and JVM, leveraging our [Android SDK](/platforms/android) and [Java SDK](/platforms/java) -- Native crash reporting for iOS and macOS, tvOS, watchOS, leveraging our [Cocoa SDK](/platforms/apple) +- Native crash reporting for iOS, macOS, tvOS and watchOS, leveraging our [Cocoa SDK](/platforms/apple) - Automatic breadcrumbs for app lifecycle and UI events From f3c852f5dde33e6dab5ce83a401f5ba5409b05b8 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Wed, 15 Mar 2023 15:11:58 +0100 Subject: [PATCH 07/11] short introduction --- .../getting-started-primer/kotlin-multiplatform.mdx | 2 ++ src/platforms/kotlin/index.mdx | 3 +-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx b/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx index 3cc6289f90210..fbdd2d254baa4 100644 --- a/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx +++ b/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx @@ -1,3 +1,5 @@ +Our Sentry Kotlin Multiplatform SDK builds on top of multiple Sentry SDKs allowing developers to use the same codebase and share code between platforms while being able to integrate Sentry's features into their applications. + ## Overview of features - Native crash reporting for Android and JVM, leveraging our [Android SDK](/platforms/android) and [Java SDK](/platforms/java) diff --git a/src/platforms/kotlin/index.mdx b/src/platforms/kotlin/index.mdx index 286419b861efd..bfd8afe4527a1 100644 --- a/src/platforms/kotlin/index.mdx +++ b/src/platforms/kotlin/index.mdx @@ -4,9 +4,8 @@ Select your platform to get started: - [Java](/platforms/java) - [Android](/platforms/android) +- [Kotlin Multiplatform](/platforms/kotlin-multiplatform) ## Kotlin Extensions - [Using Sentry SDK with Coroutines](/platforms/java/enriching-events/scopes/#kotlin-coroutines) - -We are also working on an [experimental SDK for Kotlin Multiplatform](https://github.com/getsentry/sentry-kotlin-multiplatform). Feedback welcome. From 801e97bd634668a3aa81b1729406b63a98c3697f Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Wed, 15 Mar 2023 16:27:59 +0100 Subject: [PATCH 08/11] change file type to kts for build.gradle --- .../getting-started-install/kotlin-multiplatform.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx b/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx index e3a9e4a110f8b..2eec87f19f9df 100644 --- a/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx +++ b/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx @@ -10,7 +10,7 @@ Android require disabling auto-init on Android to not clash with the ContentProv To install the Kotlin Multiplatform SDK, you need to add the following to your `build.gradle.kts` file in your shared module: -```kotlin {filename:build.gradle.kt} +```kotlin {filename:build.gradle.kts} repositories { mavenCentral() } From c89d90bc4952d5bf0d4083422a538a30ddd23815 Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Wed, 15 Mar 2023 16:44:12 +0100 Subject: [PATCH 09/11] add experimental note --- .../getting-started-primer/kotlin-multiplatform.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx b/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx index fbdd2d254baa4..6de9650a21af7 100644 --- a/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx +++ b/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx @@ -5,3 +5,9 @@ Our Sentry Kotlin Multiplatform SDK builds on top of multiple Sentry SDKs allowi - Native crash reporting for Android and JVM, leveraging our [Android SDK](/platforms/android) and [Java SDK](/platforms/java) - Native crash reporting for iOS, macOS, tvOS and watchOS, leveraging our [Cocoa SDK](/platforms/apple) - Automatic breadcrumbs for app lifecycle and UI events + + + +This SDK is currently experimental. + + From 3ec176edd70f692ecba7d85c05547c68ff5d432c Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 16 Mar 2023 10:35:50 +0100 Subject: [PATCH 10/11] review improvements --- .../drain-example/kotlin-multiplatform.mdx | 2 +- .../add-attachment/kotlin-multiplatform.mdx | 4 ++-- .../kotlin-multiplatform.mdx | 6 +++--- .../kotlin-multiplatform.mdx | 6 +++--- .../set-release/kotlin-multiplatform.mdx | 2 +- .../initialization-strategies.mdx | 17 ++++++++--------- 6 files changed, 18 insertions(+), 19 deletions(-) diff --git a/src/platform-includes/configuration/drain-example/kotlin-multiplatform.mdx b/src/platform-includes/configuration/drain-example/kotlin-multiplatform.mdx index 187144a06123b..222be9810cee6 100644 --- a/src/platform-includes/configuration/drain-example/kotlin-multiplatform.mdx +++ b/src/platform-includes/configuration/drain-example/kotlin-multiplatform.mdx @@ -1 +1 @@ -The Kotlin Multiplatform SDK utilises the native SDKs to automatically store Sentry events on the device's disk before shutdown. +The Kotlin Multiplatform SDK uses native SDKs to automatically store Sentry events on the device's disk before shutdown. diff --git a/src/platform-includes/enriching-events/add-attachment/kotlin-multiplatform.mdx b/src/platform-includes/enriching-events/add-attachment/kotlin-multiplatform.mdx index 95e2c1fe8dbd0..67422586c4eec 100644 --- a/src/platform-includes/enriching-events/add-attachment/kotlin-multiplatform.mdx +++ b/src/platform-includes/enriching-events/add-attachment/kotlin-multiplatform.mdx @@ -1,8 +1,8 @@ -To add an attachment, you can either add it to the scope or pass it to any of the `capture` methods. +To add an attachment, either add it to the scope or pass it to any of the `capture` methods. ### Passing Attachments to Capture -You may pass attachments to any of the `capture` methods, for example, when capturing an exception: +You can pass attachments to any of the `capture` methods. For example, when capturing an exception: ```kotlin import io.sentry.kotlin.multiplatform.Attachment diff --git a/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx b/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx index 2eec87f19f9df..61aa885f4bdfa 100644 --- a/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx +++ b/src/platform-includes/getting-started-install/kotlin-multiplatform.mdx @@ -1,6 +1,6 @@ ### Prerequisites (Android) -Android require disabling auto-init on Android to not clash with the ContentProvider, which auto-initializes the Sentry Android SDK. To do so, add the following to the AndroidManifest.xml file under your androidMain source set: +Android requires disabling auto-init to not clash with the ContentProvider, which auto-initializes the Sentry Android SDK. To do so, add the following to the AndroidManifest.xml file under your androidMain source set: ```xml @@ -10,7 +10,7 @@ Android require disabling auto-init on Android to not clash with the ContentProv To install the Kotlin Multiplatform SDK, you need to add the following to your `build.gradle.kts` file in your shared module: -```kotlin {filename:build.gradle.kts} +```kotlin {filename:shared/build.gradle.kts} repositories { mavenCentral() } @@ -44,5 +44,5 @@ kotlin { export("io.sentry:sentry-kotlin-multiplatform:{{ packages.version('sentry.kotlin.kmp', '0.0.1-alpha.2') }}") } } - ``` } +``` diff --git a/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx b/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx index 6de9650a21af7..aec9868cdeeff 100644 --- a/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx +++ b/src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx @@ -1,9 +1,9 @@ -Our Sentry Kotlin Multiplatform SDK builds on top of multiple Sentry SDKs allowing developers to use the same codebase and share code between platforms while being able to integrate Sentry's features into their applications. +Sentry's Kotlin Multiplatform SDK builds on top of multiple Sentry SDKs, allowing developers to use the same codebase and share code between platforms while being able to integrate Sentry's features into their applications. -## Overview of features +## Overview of Features - Native crash reporting for Android and JVM, leveraging our [Android SDK](/platforms/android) and [Java SDK](/platforms/java) -- Native crash reporting for iOS, macOS, tvOS and watchOS, leveraging our [Cocoa SDK](/platforms/apple) +- Native crash reporting for iOS, macOS, tvOS, and watchOS, leveraging our [Cocoa SDK](/platforms/apple) - Automatic breadcrumbs for app lifecycle and UI events diff --git a/src/platform-includes/set-release/kotlin-multiplatform.mdx b/src/platform-includes/set-release/kotlin-multiplatform.mdx index 97e2cba2a5d41..83b38c4a8038e 100644 --- a/src/platform-includes/set-release/kotlin-multiplatform.mdx +++ b/src/platform-includes/set-release/kotlin-multiplatform.mdx @@ -7,4 +7,4 @@ Sentry.init(context) { options -> } ``` -If no release name is set the SDK creates a default depending on the native platform. +If no release name is set, the SDK creates a default, depending on the native platform. diff --git a/src/platforms/kotlin-multiplatform/initialization-strategies.mdx b/src/platforms/kotlin-multiplatform/initialization-strategies.mdx index efb6aaaf0cd4f..39a046a37ca13 100644 --- a/src/platforms/kotlin-multiplatform/initialization-strategies.mdx +++ b/src/platforms/kotlin-multiplatform/initialization-strategies.mdx @@ -1,7 +1,7 @@ --- title: Initialization Strategies sidebar_order: 0 -description: "Different strategies how to initialize the Kotlin Multiplatform SDK." +description: "Strategies for initializing the Kotlin Multiplatform SDK." --- When it comes to initializing a Kotlin Multiplatform SDK, there are three strategies to consider: @@ -9,14 +9,13 @@ When it comes to initializing a Kotlin Multiplatform SDK, there are three strate - [Platform specific initializers](#platform-specific-initializers) - [Hybrid approach](#hybrid-approach) -## Shared initializer +## Shared Initializer The shared initializer approach involves initializing the SDK in your shared codebase, using the same configuration options for all platforms. This approach is ideal for projects that prioritize consistency across platforms and do not require platform-specific customizations. Using a shared initializer provides a single source of truth for your SDK's configuration options. This can simplify maintenance and debugging efforts, as you only need to update one codebase for all platforms. -Inside a Kotlin file in your commonMain e.g. `AppSetup.kt` or however you want to call it and create a function that will initialize the SDK. -Afterwards you can call it in an early lifecycle stage in your platforms. +To initialize the SDK, create a Kotlin file in your `commonMain` e.g. `AppSetup.kt`, (or whatever you decide to call it), and create an initialization function. You'll then be able to call it in an early lifecycle stage in your platforms. ```kotlin {filename:AppSetup.kt} import io.sentry.kotlin.multiplatform.Context @@ -58,9 +57,9 @@ func application( } ``` -## Platform specific initializers +## Platform-Specific Initializers -Platform specific initializers allow for customization of the SDK's configuration options on a per-platform basis. This approach can be particularly useful when your SDK requires platform specific functionality or performance optimizations. +Platform-specific initializers allow for customization of the SDK's configuration options on a per-platform basis. This approach can be particularly useful when your SDK requires platform-specific functionality or performance optimizations. With platform-specific initializers, you can initialize the SDK directly in the target platform's codebase. This approach gives you the flexibility to fine-tune the SDK's behavior to meet the unique needs of each platform. @@ -96,8 +95,8 @@ func application( } ``` -## Hybrid approach +## Hybrid Approach -It is also possible to mix the two initialization strategies by creating custom sourcesets that only target specific platforms. This allows you to use a shared initializer for some platforms while utilizing platform-specific initializers for others. +It's also possible to mix the two initialization strategies by creating custom `sourceSets` that only target specific platforms. This allows you to use a shared initializer for some platforms while utilizing platform-specific initializers for others. -For example, you may choose to use a shared initializer for Android and iOS platforms while using a platform specific initializer for the watchOS and tvOS platform. This approach provides a balance between consistency and customization. +For example, you may choose to use a shared initializer for Android and iOS platforms, while using a platform-specific initializer for the watchOS and tvOS platform. This approach provides a balance between consistency and customization. From 8ae8f0d380a35bedb5423daf005f4917d982570d Mon Sep 17 00:00:00 2001 From: Giancarlo Buenaflor Date: Thu, 16 Mar 2023 11:48:45 +0100 Subject: [PATCH 11/11] review improvements --- src/platforms/common/configuration/filtering.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/platforms/common/configuration/filtering.mdx b/src/platforms/common/configuration/filtering.mdx index e3531e7d0a53c..ac4af6fca421c 100644 --- a/src/platforms/common/configuration/filtering.mdx +++ b/src/platforms/common/configuration/filtering.mdx @@ -7,7 +7,7 @@ notSupported: - kotlin-multiplatform --- -Adding Sentry to your app gives you a great deal of very valuable information about errors and performance you wouldn't otherwise get. And lots of information is good -- as long as it's the right information, at a reasonable volume. +When you add Sentry to your app, you get a lot of valuable information about errors and performance. And lots of information is good -- as long as it's the right information, at a reasonable volume. The Sentry SDKs have several configuration options to help you filter out events.