@danieljvdm/dev-kit 1.0.1 → 2.0.0

package/skills/sentry/references/sdks/android/integrations.md

@@ -0,0 +1,48 @@
+# Integration Reference — Sentry Android SDK
+
+### Built-in (Auto-Enabled)
+
+These integrations activate automatically when `SentryAndroid.init()` is called:
+
+| Integration                           | What it does                                                           |
+| ------------------------------------- | ---------------------------------------------------------------------- |
+| `UncaughtExceptionHandlerIntegration` | Captures all uncaught Java/Kotlin exceptions                           |
+| `AnrIntegration`                      | ANR detection via watchdog thread (5s) + ApplicationExitInfo (API 30+) |
+| `NdkIntegration`                      | Native (C/C++) crash capture via `sentry-native`                       |
+| `ActivityLifecycleIntegration`        | Auto-instruments Activity create/resume/pause for TTID/TTFD            |
+| `AppStartMetrics`                     | Measures cold/warm/hot app start time                                  |
+| `NetworkBreadcrumbsIntegration`       | Records connectivity changes as breadcrumbs                            |
+| `SystemEventsBreadcrumbsIntegration`  | Records battery, screen on/off, etc.                                   |
+| `AppLifecycleIntegration`             | Records foreground/background transitions                              |
+| `UserInteractionIntegration`          | Breadcrumbs for taps, swipes, input events                             |
+| `CurrentActivityIntegration`          | Tracks active Activity for context                                     |
+
+### Optional Integrations
+
+Add the artifact to your `dependencies {}` block (versions managed by BOM):
+
+| Integration           | Artifact                                | When to add                                     |
+| --------------------- | --------------------------------------- | ----------------------------------------------- |
+| **Timber**            | `io.sentry:sentry-android-timber`       | App uses Timber for logging                     |
+| **Fragment**          | `io.sentry:sentry-android-fragment`     | App uses Jetpack Fragments (lifecycle tracing)  |
+| **Compose**           | `io.sentry:sentry-compose-android`      | App uses Jetpack Compose (navigation + masking) |
+| **Navigation**        | `io.sentry:sentry-android-navigation`   | App uses Jetpack Navigation Component           |
+| **OkHttp**            | `io.sentry:sentry-okhttp`               | App uses OkHttp or Retrofit                     |
+| **Room/SQLite**       | `io.sentry:sentry-android-sqlite`       | App uses Room or raw SQLite                     |
+| **Apollo 3**          | `io.sentry:sentry-apollo-3`             | App uses Apollo GraphQL v3                      |
+| **Apollo 4**          | `io.sentry:sentry-apollo-4`             | App uses Apollo GraphQL v4                      |
+| **Kotlin Extensions** | `io.sentry:sentry-kotlin-extensions`    | Kotlin coroutines context propagation           |
+| **Ktor Client**       | `io.sentry:sentry-ktor-client`          | App uses Ktor HTTP client                       |
+| **LaunchDarkly**      | `io.sentry:sentry-launchdarkly-android` | App uses LaunchDarkly feature flags             |
+
+### Gradle Plugin Bytecode Instrumentation
+
+The plugin can inject instrumentation automatically (no source changes):
+
+| Feature    | Instruments                            | Enable via                        |
+| ---------- | -------------------------------------- | --------------------------------- |
+| `DATABASE` | Room DAO, SupportSQLiteOpenHelper      | `tracingInstrumentation.features` |
+| `FILE_IO`  | FileInputStream, FileOutputStream      | `tracingInstrumentation.features` |
+| `OKHTTP`   | OkHttpClient.Builder automatically     | `tracingInstrumentation.features` |
+| `COMPOSE`  | NavHostController auto-instrumentation | `tracingInstrumentation.features` |
+| `LOGCAT`   | `android.util.Log` capturing           | `tracingInstrumentation.features` |

package/skills/sentry/references/sdks/android/logging.md

@@ -0,0 +1,374 @@
+# Logging — Sentry Android SDK
+
+> **Minimum SDK:** `io.sentry:sentry-android:8.12.0`\
+> **Status:** Stable\
+> **Enabled by default:** No — must opt in explicitly\
+> **Docs:** https://docs.sentry.io/platforms/android/logs/
+
+---
+
+## Overview
+
+Sentry Structured Logs capture application log events as searchable, filterable records
+in the Sentry Logs UI. Unlike breadcrumbs (which are attached to errors), structured
+logs are standalone events with typed attributes and are queryable independently.
+
+Logging is **opt-in** — the feature is entirely inert until
+`options.logs.isEnabled = true` is set.
+
+---
+
+## Enabling Logs
+
+**Code (preferred — allows dynamic configuration):**
+
+```kotlin
+SentryAndroid.init(this) { options ->
+    options.dsn = "https://YOUR_KEY@sentry.io/YOUR_PROJECT_ID"
+    options.logs.isEnabled = true
+}
+```
+
+**AndroidManifest.xml:**
+
+```xml
+<application>
+    <meta-data
+        android:name="io.sentry.logs.enabled"
+        android:value="true" />
+</application>
+```
+
+---
+
+## Configuration
+
+```kotlin
+SentryAndroid.init(this) { options ->
+    options.logs.isEnabled = true
+
+    // Optional: filter or mutate logs before they are sent
+    options.logs.setBeforeSend { event ->
+        // Drop TRACE logs in production
+        if (!BuildConfig.DEBUG && event.level == SentryLogLevel.TRACE) {
+            return@setBeforeSend null  // null = drop the event
+        }
+        // Redact PII
+        val body = event.body ?: return@setBeforeSend event
+        if (body.contains("password", ignoreCase = true)) {
+            event.setBody("[REDACTED]")
+        }
+        event
+    }
+}
+```
+
+### Configuration Reference
+
+| Option               | Type                     | Default | Description                                                             |
+| -------------------- | ------------------------ | ------- | ----------------------------------------------------------------------- |
+| `logs.isEnabled`     | `Boolean`                | `false` | Master switch — must be `true` for all logging features                 |
+| `logs.setBeforeSend` | `BeforeSendLogCallback?` | `null`  | Filter or mutate log events before transmission. Return `null` to drop. |
+
+---
+
+## Code Examples
+
+### Basic Level Methods
+
+```kotlin
+import io.sentry.Sentry
+import io.sentry.SentryLogLevel
+import io.sentry.SentryAttribute
+import io.sentry.SentryAttributes
+import io.sentry.logger.SentryLogParameters
+
+// Six log levels — all accept printf-style format strings
+Sentry.logger().trace("Entering %s.%s()", className, methodName)
+Sentry.logger().debug("Cache lookup for key: %s", cacheKey)
+Sentry.logger().info("User %s logged in", userId)
+Sentry.logger().warn("Rate limit approaching: %d / %d requests used", current, max)
+Sentry.logger().error("Payment failed after %d retries", retries)
+Sentry.logger().fatal("Database unavailable: %s", host)
+```
+
+**Java:**
+
+```java
+Sentry.logger().info("User %s logged in", userId);
+Sentry.logger().error("Payment failed after %d retries", retries);
+```
+
+### Structured Attributes
+
+Attach typed key-value pairs to make log events queryable by attribute values in Sentry:
+
+```kotlin
+Sentry.logger().log(
+    SentryLogLevel.INFO,
+    SentryLogParameters.create(
+        SentryAttributes.of(
+            SentryAttribute.stringAttribute("user.id",        userId),
+            SentryAttribute.stringAttribute("order.id",       orderId),
+            SentryAttribute.stringAttribute("payment.method", "card"),
+            SentryAttribute.booleanAttribute("is_retry",       false),
+            SentryAttribute.integerAttribute("item_count",     3),
+            SentryAttribute.doubleAttribute("total_usd",       49.99)
+        )
+    ),
+    "Checkout completed for user %s",
+    userId
+)
+```
+
+**Attribute factory methods:**
+
+```kotlin
+SentryAttribute.stringAttribute("key",  "value")     // String
+SentryAttribute.booleanAttribute("key",  true)        // Boolean
+SentryAttribute.integerAttribute("key",  42)          // Int / Long
+SentryAttribute.doubleAttribute("key",   3.14)        // Double / Float
+SentryAttribute.named("key", anyObject)               // type inferred at runtime
+```
+
+**From a map:**
+
+```kotlin
+val attrs = SentryAttributes.fromMap(mapOf(
+    "user.id"    to userId,
+    "request.id" to requestId,
+    "duration"   to durationMs
+))
+Sentry.logger().log(SentryLogLevel.INFO, SentryLogParameters.create(attrs), "API call completed")
+```
+
+### Custom Timestamp (Backfilling)
+
+```kotlin
+val ts = SentryAutoDateProvider().now()
+Sentry.logger().log(
+    SentryLogLevel.INFO,
+    SentryLogParameters.create(
+        ts,
+        SentryAttributes.of(
+            SentryAttribute.stringAttribute("event", "purchase_complete"),
+            SentryAttribute.stringAttribute("order.id", orderId)
+        )
+    ),
+    "Order %s fulfilled",
+    orderId
+)
+```
+
+### Production Pattern — Screen Lifecycle
+
+```kotlin
+class ProductDetailActivity : AppCompatActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        val productId = intent.getStringExtra("product_id")
+
+        Sentry.logger().info(
+            SentryLogParameters.create(
+                SentryAttributes.of(
+                    SentryAttribute.stringAttribute("screen", "ProductDetail"),
+                    SentryAttribute.stringAttribute("product.id", productId ?: "unknown")
+                )
+            ),
+            "Screen opened: ProductDetail"
+        )
+    }
+}
+```
+
+### Production Pattern — API Call Logging
+
+```kotlin
+suspend fun fetchUserProfile(userId: String): UserProfile {
+    Sentry.logger().debug("Fetching profile for user %s", userId)
+    val t0 = SystemClock.elapsedRealtime()
+
+    return try {
+        val profile = api.getUser(userId)
+        Sentry.logger().info(
+            SentryLogParameters.create(
+                SentryAttributes.of(
+                    SentryAttribute.stringAttribute("user.id", userId),
+                    SentryAttribute.integerAttribute("duration_ms", (SystemClock.elapsedRealtime() - t0).toInt())
+                )
+            ),
+            "Profile fetch succeeded for user %s",
+            userId
+        )
+        profile
+    } catch (e: Exception) {
+        Sentry.logger().error(
+            SentryLogParameters.create(
+                SentryAttributes.of(
+                    SentryAttribute.stringAttribute("user.id", userId),
+                    SentryAttribute.integerAttribute("duration_ms", (SystemClock.elapsedRealtime() - t0).toInt()),
+                    SentryAttribute.stringAttribute("error", e.message ?: "unknown")
+                )
+            ),
+            "Profile fetch failed for user %s",
+            userId
+        )
+        throw e
+    }
+}
+```
+
+---
+
+## Timber Integration
+
+`SentryTimberIntegration` bridges Timber logs into the Sentry Logs pipeline.
+Requires `sentry-android-timber`.
+
+**Dependency:**
+
+```groovy
+implementation("io.sentry:sentry-android-timber:8.33.0")
+```
+
+**Setup:**
+
+```kotlin
+SentryAndroid.init(this) { options ->
+    options.logs.isEnabled = true
+
+    options.addIntegration(
+        SentryTimberIntegration(
+            minEventLevel      = SentryLevel.ERROR,      // Timber.e() → Sentry error events
+            minBreadcrumbLevel = SentryLevel.INFO,       // Timber.i() → breadcrumbs
+            minLogsLevel       = SentryLogLevel.DEBUG,   // Timber.d() → Sentry structured logs
+        )
+    )
+}
+
+// Plant Timber separately — SDK does not plant for you
+if (BuildConfig.DEBUG) Timber.plant(Timber.DebugTree())
+```
+
+**Timber priority → SentryLogLevel mapping:**
+
+| Timber Priority | `SentryLogLevel` |
+| --------------- | ---------------- |
+| `Log.VERBOSE`   | `TRACE`          |
+| `Log.DEBUG`     | `DEBUG`          |
+| `Log.INFO`      | `INFO`           |
+| `Log.WARN`      | `WARN`           |
+| `Log.ERROR`     | `ERROR`          |
+| `Log.ASSERT`    | `FATAL`          |
+
+Each Timber-sourced log carries `sentry.origin = "auto.log.timber"` for filtering in
+`beforeSend`.
+
+---
+
+## Logcat Auto-Integration (Gradle Plugin)
+
+With the Sentry Android Gradle plugin, `android.util.Log` calls are
+bytecode-instrumented at build time and forwarded to Sentry Logs automatically — **no
+source code changes needed**:
+
+```groovy
+// android/build.gradle (module)
+sentry {
+    autoInstallation.enabled = true
+    tracingInstrumentation {
+        features = [InstrumentationFeature.LOGCAT]
+    }
+}
+```
+
+Without the plugin, only manual `Sentry.logger()` calls and the Timber integration
+capture logs.
+
+---
+
+## Auto-Attached Attributes
+
+The SDK automatically enriches every log event with the following attributes:
+
+| Attribute Key                          | Value                                                  | Notes                                             |
+| -------------------------------------- | ------------------------------------------------------ | ------------------------------------------------- |
+| `sentry.origin`                        | `"manual"` / `"auto.log.timber"` / `"auto.log.logcat"` | Per integration                                   |
+| `sentry.message.template`              | Original format string                                 | e.g. `"User %s logged in"`                        |
+| `sentry.message.parameter.0` … `.N`    | Format argument values                                 |                                                   |
+| `sentry.sdk.name`                      | `"sentry.java.android"`                                |                                                   |
+| `sentry.sdk.version`                   | `"8.33.0"`                                             |                                                   |
+| `sentry.environment`                   | Configured environment                                 |                                                   |
+| `sentry.release`                       | Configured release string                              |                                                   |
+| `sentry.replay_id`                     | Active replay session UUID                             | Only when Session Replay is recording             |
+| `sentry._internal.replay_is_buffering` | `"true"`                                               | Only in `onErrorSampleRate` buffer mode           |
+| `user.id`                              | From `scope.user.id`                                   | Added regardless of `sendDefaultPii` since 8.33.0 |
+| `user.name`                            | From `scope.user.username`                             |                                                   |
+| `user.email`                           | From `scope.user.email`                                |                                                   |
+
+> **8.33.0 change:** `user.id`, `user.name`, `user.email` now attach to logs regardless
+> of `sendDefaultPii`. Use `beforeSend` to suppress PII if needed.
+
+---
+
+## Log Levels Reference
+
+| Level   | `SentryLogLevel` constant | OTel Severity | When to Use                                      |
+| ------- | ------------------------- | ------------- | ------------------------------------------------ |
+| `trace` | `TRACE` (1)               | 1             | Step-by-step internals, loop iterations          |
+| `debug` | `DEBUG` (5)               | 5             | Development diagnostics                          |
+| `info`  | `INFO` (9)                | 9             | Business events, user actions, state transitions |
+| `warn`  | `WARN` (13)               | 13            | Recoverable errors, approaching limits           |
+| `error` | `ERROR` (17)              | 17            | Failures requiring investigation                 |
+| `fatal` | `FATAL` (21)              | 21            | Unrecoverable failures — app or subsystem down   |
+
+---
+
+## Batch Processing
+
+The SDK batches log events for efficiency:
+
+| Parameter        | Value                                                                   |
+| ---------------- | ----------------------------------------------------------------------- |
+| Flush delay      | 5 seconds after the first queued event                                  |
+| Max batch size   | 100 events per HTTP envelope                                            |
+| Max queue size   | 1,000 events (events silently dropped above this)                       |
+| Background flush | Yes — `AndroidLoggerBatchProcessor` flushes when app goes to background |
+
+---
+
+## Best Practices
+
+1. **Enable in `Application.onCreate()`** — set `options.logs.isEnabled = true` before
+   any log calls
+2. **Use structured attributes** — pass typed key-value pairs instead of embedding
+   values in message strings; they become queryable columns in the Logs UI
+3. **Use `beforeSend` for level filtering** — drop `TRACE`/`DEBUG` in production to
+   reduce quota usage
+4. **Redact PII in `beforeSend`** — since 8.33.0 user attributes attach regardless of
+   `sendDefaultPii`
+5. **Prefer `Sentry.logger()` over Timber for new code** — direct API provides full type
+   safety for attributes
+6. **Plant Timber separately** — `SentryTimberIntegration` does not call
+   `Timber.plant()`; you must do it yourself
+7. **Don’t call `Sentry.logger()` before `SentryAndroid.init()`** — calls before init
+   are silently dropped
+8. **Keep queue headroom** — avoid bursts that exceed 1,000 queued events; excess is
+   silently dropped
+
+---
+
+## Troubleshooting
+
+| Issue                                              | Solution                                                                                                                    |
+| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Logs not appearing in Sentry                       | Verify `options.logs.isEnabled = true` is set in `SentryAndroid.init()` — the feature is disabled by default                |
+| Logs appearing but missing attributes              | Ensure you pass a `SentryLogParameters` with `SentryAttributes.of(...)` — plain format args are not queryable as attributes |
+| Timber logs not forwarded                          | Add `SentryTimberIntegration` to `options.addIntegration()` and plant a `Timber.DebugTree()` separately                     |
+| Timber logs not reaching Sentry as structured logs | Check `minLogsLevel` on `SentryTimberIntegration` — default is `INFO`; set to `DEBUG` to capture debug-level logs           |
+| Logs disappear silently under heavy load           | Queue is capped at 1,000 events; use `beforeSend` to drop verbose levels before they queue up                               |
+| `user.id` appearing in logs unexpectedly           | Since SDK 8.33.0, user fields attach regardless of `sendDefaultPii`; use `beforeSend` to strip them                         |
+| Logcat `Log.*` calls not captured                  | Requires the Sentry Android Gradle plugin with `InstrumentationFeature.LOGCAT` enabled at build time                        |
+| `beforeSend` not called                            | Check that `options.logs.isEnabled = true` — `beforeSend` is only invoked when the feature is enabled                       |
+| Logs lost on crash                                 | Known limitation: in-memory queued events may not reach Sentry before the process is killed                                 |