Add Sentry KMP integration guide for Compose Multiplatform

Co-authored-by: giancarlo.buenaflor <[email protected]>

Author: cursoragent

sentry-kmp-compose-multiplatform-integration-guide.mdx

@@ -0,0 +1,277 @@
+---
+title: "Sentry Kotlin Multiplatform in Compose Multiplatform"
+description: "Learn how to integrate Sentry's Kotlin Multiplatform SDK into your Compose Multiplatform project for cross-platform error tracking."
+sdk: sentry.kotlin.multiplatform
+categories:
+  - kotlin
+  - multiplatform
+sidebar_order: 15
+---
+
+# Sentry Kotlin Multiplatform in Compose Multiplatform
+
+<Alert level="warning" title="Experimental Support">
+While Sentry's Kotlin Multiplatform SDK works in Compose Multiplatform projects, it isn't natively supported or fully tested for CMP. Some features may behave unexpectedly or provide incomplete data. Use with caution in production environments.
+</Alert>
+
+## Overview
+
+**Compose Multiplatform** is JetBrains' declarative UI framework that allows you to build native user interfaces for desktop, web, and mobile platforms using a single Kotlin codebase. It extends Jetpack Compose beyond Android to create truly multiplatform applications.
+
+**Sentry's Kotlin Multiplatform SDK** provides error tracking and performance monitoring capabilities across multiple Kotlin targets. While the SDK functions in Compose Multiplatform projects using the same APIs as pure KMP setups, it's important to note:
+
+- ✅ **Supported**: The KMP SDK works in CMP projects
+- ⚠️ **Not CMP-native**: No specific CMP optimizations or testing
+- 🔍 **Untested edge cases**: Some platform-specific behaviors may be incomplete
+
+## Prerequisites
+
+Before integrating Sentry into your Compose Multiplatform project, ensure you have:
+
+### Development Environment
+- **Kotlin 1.9.0+** and compatible JVM (Java 11+)
+- **Gradle 7.6+** with Kotlin DSL support
+- **Compose Multiplatform plugin** configured in your project
+
+### Project Setup
+- A working Compose Multiplatform project targeting your desired platforms:
+  - **JVM/Desktop**: Windows, macOS, Linux
+  - **Android**: Mobile applications
+  - **iOS**: iPhone/iPad applications (experimental)
+
+### Sentry Configuration
+- A [Sentry project](https://sentry.io) with your **DSN** (Data Source Name)
+- Basic understanding of Sentry error tracking concepts
+
+## Installation
+
+### 1. Add Sentry Dependency
+
+Add the Sentry Kotlin Multiplatform SDK to your `commonMain` source set in `build.gradle.kts`:
+
+```kotlin {filename:build.gradle.kts}
+kotlin {
+    sourceSets {
+        commonMain.dependencies {
+            implementation("io.sentry:sentry-kotlin-multiplatform:0.7.1")
+        }
+    }
+}
+```
+
+### 2. Platform-Specific Considerations
+
+The Sentry KMP SDK automatically includes platform-specific artifacts. No additional dependencies are required for basic functionality across JVM, Android, and iOS targets.
+
+<Alert level="info">
+Platform-specific features (like native crash reporting) may not be fully available or tested in CMP contexts.
+</Alert>
+
+## Basic Usage in CMP
+
+### 1. Initialize Sentry
+
+Initialize Sentry in your main application entry point, typically in your `main()` function or `App` composable:
+
+```kotlin {filename:App.kt}
+import io.sentry.kotlin.multiplatform.Sentry
+import androidx.compose.runtime.Composable
+
+@Composable
+fun App() {
+    // Initialize Sentry when your app starts
+    Sentry.init { options ->
+        options.dsn = "___PUBLIC_DSN___"
+        options.debug = true // Enable for development
+        options.environment = "development"
+    }
+    
+    // Your Compose UI content
+    MainContent()
+}
+
+@Composable
+fun MainContent() {
+    // Your app's UI components
+}
+```
+
+### 2. Capture Errors and Exceptions
+
+Use Sentry to capture exceptions and errors throughout your application:
+
+```kotlin {filename:ErrorHandling.kt}
+import io.sentry.kotlin.multiplatform.Sentry
+
+@Composable
+fun ExampleScreen() {
+    Button(
+        onClick = {
+            try {
+                // Risky operation that might fail
+                performRiskyOperation()
+            } catch (e: Exception) {
+                // Capture the exception with Sentry
+                Sentry.captureException(e)
+                // Handle the error in your UI
+            }
+        }
+    ) {
+        Text("Perform Action")
+    }
+}
+
+fun performRiskyOperation() {
+    // Example operation that might throw
+    throw RuntimeException("Something went wrong!")
+}
+```
+
+### 3. Add Breadcrumbs for Context
+
+Breadcrumbs help trace user actions leading up to an error:
+
+```kotlin {filename:BreadcrumbExample.kt}
+import io.sentry.kotlin.multiplatform.Sentry
+import io.sentry.kotlin.multiplatform.protocol.Breadcrumb
+
+@Composable
+fun NavigationExample() {
+    LaunchedEffect(Unit) {
+        // Add breadcrumb when screen loads
+        Sentry.addBreadcrumb(
+            Breadcrumb().apply {
+                message = "User navigated to main screen"
+                category = "navigation"
+                level = SentryLevel.INFO
+            }
+        )
+    }
+    
+    Button(
+        onClick = {
+            // Add breadcrumb for user actions
+            Sentry.addBreadcrumb("User clicked primary button", "ui.click")
+            handleButtonClick()
+        }
+    ) {
+        Text("Click Me")
+    }
+}
+```
+
+## Feature Support
+
+The following Sentry KMP features **should** work in Compose Multiplatform projects, though with varying levels of reliability:
+
+### ✅ Core Features (Expected to Work)
+- **Error Tracking**: Exception capture and reporting
+- **Breadcrumbs**: Manual breadcrumb creation and context tracking
+- **Custom Tags**: Adding metadata to events
+- **User Context**: Setting user information
+- **Environment Configuration**: Debug modes, environment settings
+
+### ⚠️ Advanced Features (Partially Tested)
+- **Performance Monitoring**: Transaction tracking (basic support)
+- **Attachments**: File and screenshot attachments (platform-dependent)
+- **Release Health**: Session tracking (may have gaps)
+
+### ❓ Platform-Specific Features (Unknown Status)
+- **Native Crash Reporting**: OS-level crash detection
+- **Automatic Error Boundary**: UI framework integration
+- **Platform-Specific Context**: Device/OS information
+
+## Known Limitations & Caveats
+
+<Alert level="warning" title="Important Considerations">
+Keep these limitations in mind when using Sentry KMP in Compose Multiplatform:
+</Alert>
+
+### Untested CMP Behaviors
+- **Compose Navigation**: Screen transition tracking may be incomplete
+- **State Management**: Compose state-related errors might not be captured optimally
+- **Hot Reload**: Development-time behavior with Compose hot reload is unknown
+
+### Data Discrepancies
+- **Performance Metrics**: Frame rates and UI performance data may be inaccurate
+- **Platform Context**: Device information might be missing or incorrect on some targets
+- **Session Tracking**: App lifecycle events may not align with Compose lifecycle
+
+### Missing Platform Hooks
+- **Desktop Platforms**: Limited system integration compared to mobile SDKs
+- **iOS Integration**: Native iOS features may not work as expected
+- **WebAssembly**: If targeting web, functionality will be significantly limited
+
+## Troubleshooting Tips
+
+### Common Setup Issues
+
+**Problem**: Events not appearing in Sentry
+```kotlin
+// ❌ Incorrect: DSN not set or invalid
+Sentry.init { } // Missing DSN
+
+// ✅ Correct: Always set your DSN
+Sentry.init { options ->
+    options.dsn = "___PUBLIC_DSN___"
+    options.debug = true // Helps identify issues
+}
+```
+
+**Problem**: Exceptions not being captured
+```kotlin
+// ❌ Incorrect: Exception swallowed silently
+try {
+    riskyOperation()
+} catch (e: Exception) {
+    // Silent failure
+}
+
+// ✅ Correct: Always capture exceptions
+try {
+    riskyOperation()
+} catch (e: Exception) {
+    Sentry.captureException(e)
+    handleError(e)
+}
+```
+
+### Verification Steps
+
+1. **Check Sentry Dashboard**: Look for events in your Sentry project dashboard
+2. **Enable Debug Mode**: Set `options.debug = true` to see SDK logs
+3. **Test Exception Capture**: Manually trigger an exception to verify capture
+4. **Review Platform Logs**: Check console output for Sentry-related messages
+
+### Debug Configuration
+
+```kotlin {filename:DebugConfig.kt}
+Sentry.init { options ->
+    options.dsn = "___PUBLIC_DSN___"
+    options.debug = true
+    options.beforeSend = { event ->
+        println("Sending event: ${event.eventId}")
+        event // Return event to send, or null to drop
+    }
+}
+```
+
+## Next Steps & Updates
+
+### Stay Updated
+- **Watch Official Docs**: Monitor [Sentry's Kotlin documentation](https://docs.sentry.io/platforms/kotlin/) for CMP-specific updates
+- **GitHub Repository**: Follow the [sentry-kotlin-multiplatform repository](https://github.com/getsentry/sentry-kotlin-multiplatform) for issues and improvements
+- **Community Feedback**: Report CMP-specific issues to help improve support
+
+### Recommended Practices
+- **Start Small**: Begin with basic error tracking before adding advanced features
+- **Test Thoroughly**: Verify functionality on all your target platforms
+- **Monitor Performance**: Watch for any performance impacts on your Compose UI
+- **Fallback Plans**: Have alternative error handling for critical app functions
+
+### Future Considerations
+Native Compose Multiplatform support is not currently on Sentry's official roadmap, but community feedback and adoption may influence future development priorities.
+
+<Alert level="info" title="Contributing">
+If you encounter CMP-specific issues or have suggestions for better integration, consider contributing to the [Sentry Kotlin Multiplatform project](https://github.com/getsentry/sentry-kotlin-multiplatform) or opening feature requests.
+</Alert>