@danieljvdm/dev-kit 1.0.1 → 2.0.0

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

@@ -0,0 +1,288 @@
+# Metrics — Sentry Android SDK
+
+> **Minimum SDK:** `io.sentry:sentry-android:8.30.0`\
+> **Enabled by default:** Yes — no opt-in required\
+> **Docs:** https://docs.sentry.io/platforms/android/metrics/
+
+---
+
+## Overview
+
+Sentry Metrics lets you track counters, distributions, and gauges from your Android app.
+Metrics are sent to Sentry and appear in the **Metrics** tab where you can create charts
+and alerts.
+
+> **No Set metric type.** Unlike some observability platforms, this SDK does **not**
+> have a `set()` method for tracking unique values.
+> Only **Counter**, **Distribution**, and **Gauge** are available.
+
+---
+
+## Configuration
+
+Metrics is enabled by default.
+To disable or add filtering:
+
+```kotlin
+SentryAndroid.init(this) { options ->
+    // Disable metrics entirely
+    options.metrics.setEnabled(false)
+
+    // Or filter metrics before they are sent
+    options.metrics.setBeforeSend { metric, _ ->
+        // Drop debug-prefixed metrics in production
+        if (!BuildConfig.DEBUG && metric.name.startsWith("debug.")) {
+            return@setBeforeSend null  // null = drop the metric
+        }
+        metric
+    }
+}
+```
+
+**Via AndroidManifest.xml:**
+
+```xml
+<meta-data android:name="io.sentry.metrics.enabled" android:value="false" />
+```
+
+### Configuration Reference
+
+| Option                  | Type                        | Default | Description                                                          |
+| ----------------------- | --------------------------- | ------- | -------------------------------------------------------------------- |
+| `metrics.isEnabled`     | `Boolean`                   | `true`  | Master switch — metrics are ON by default                            |
+| `metrics.setBeforeSend` | `BeforeSendMetricCallback?` | `null`  | Filter or mutate metrics before transmission. Return `null` to drop. |
+
+---
+
+## Code Examples
+
+### Counter
+
+Track how many times something happens.
+Default increment is `1.0`.
+
+```kotlin
+import io.sentry.Sentry
+import io.sentry.metrics.MetricsUnit
+import io.sentry.metrics.SentryMetricsParameters
+import io.sentry.SentryAttribute
+import io.sentry.SentryAttributes
+
+// Simple event count
+Sentry.metrics().count("ui.button_tap")
+
+// With explicit increment value
+Sentry.metrics().count("feature.items_processed", 25.0)
+
+// With unit
+Sentry.metrics().count("network.bytes_sent", 8_192.0, MetricsUnit.Information.BYTE)
+
+// With attributes (custom dimensions for filtering/grouping)
+Sentry.metrics().count(
+    "feature.used",
+    1.0,
+    null, // no unit for dimensionless counters
+    SentryMetricsParameters.create(
+        SentryAttributes.of(
+            SentryAttribute.stringAttribute("feature",   "dark_mode"),
+            SentryAttribute.stringAttribute("user_tier", "premium")
+        )
+    )
+)
+```
+
+### Distribution
+
+Record individual measurements — each call adds one data point to a histogram.
+Use for durations, sizes, and similar measurements.
+
+```kotlin
+// Response time
+Sentry.metrics().distribution("api.response_time", 187.5, MetricsUnit.Duration.MILLISECOND)
+
+// File size
+Sentry.metrics().distribution("image.upload_size", fileBytes.toDouble(), MetricsUnit.Information.BYTE)
+
+// With attributes
+Sentry.metrics().distribution(
+    "api.response_time",
+    elapsed.toDouble(),
+    MetricsUnit.Duration.MILLISECOND,
+    SentryMetricsParameters.create(
+        SentryAttributes.of(
+            SentryAttribute.stringAttribute("endpoint",   "/api/v2/users"),
+            SentryAttribute.stringAttribute("http.method", "GET"),
+            SentryAttribute.integerAttribute("http.status", responseCode)
+        )
+    )
+)
+```
+
+### Gauge
+
+Capture a point-in-time snapshot of a value that can go up or down.
+Use for current levels, queue depths, and resource utilization.
+
+```kotlin
+// Active downloads
+Sentry.metrics().gauge("app.active_downloads", activeDownloads.toDouble())
+
+// Memory usage
+val usedMemory = (Runtime.getRuntime().totalMemory() - Runtime.getRuntime().freeMemory()) / 1_048_576.0
+Sentry.metrics().gauge("app.memory_used_mb", usedMemory)
+
+// Queue depth
+Sentry.metrics().gauge("queue.pending_tasks", pendingTasks.toDouble())
+```
+
+### Backfilling with Custom Timestamp
+
+```kotlin
+Sentry.metrics().distribution(
+    "checkout.duration",
+    checkoutDurationMs.toDouble(),
+    MetricsUnit.Duration.MILLISECOND,
+    SentryMetricsParameters.create(
+        SentryAutoDateProvider().now(),   // custom timestamp
+        SentryAttributes.of(
+            SentryAttribute.stringAttribute("payment_method", "card"),
+            SentryAttribute.booleanAttribute("coupon_applied",  true)
+        )
+    )
+)
+```
+
+### Practical Example — Tracking Checkout Flow
+
+```kotlin
+class CheckoutViewModel : ViewModel() {
+
+    fun checkout(cart: Cart) {
+        val t0 = SystemClock.elapsedRealtime()
+
+        viewModelScope.launch {
+            try {
+                val order = repository.submitOrder(cart)
+
+                // Count successful checkouts
+                Sentry.metrics().count(
+                    "checkout.success",
+                    1.0,
+                    null,
+                    SentryMetricsParameters.create(
+                        SentryAttributes.of(
+                            SentryAttribute.stringAttribute("payment_method", cart.paymentMethod),
+                            SentryAttribute.integerAttribute("item_count", cart.items.size)
+                        )
+                    )
+                )
+
+                // Record checkout duration
+                Sentry.metrics().distribution(
+                    "checkout.duration",
+                    (SystemClock.elapsedRealtime() - t0).toDouble(),
+                    MetricsUnit.Duration.MILLISECOND
+                )
+
+                // Record order value
+                Sentry.metrics().distribution("order.value_usd", cart.totalUsd)
+
+            } catch (e: Exception) {
+                Sentry.metrics().count("checkout.failure")
+                throw e
+            }
+        }
+    }
+}
+```
+
+---
+
+## Units Reference — `MetricsUnit`
+
+Use `MetricsUnit` constants for well-known units.
+Pass `null` for dimensionless values.
+
+> **Custom unit strings are not supported.** Only `MetricsUnit.*` constants produce
+> correct rendering in the Sentry UI. Passing an arbitrary string (e.g., `"frames"`) is
+> accepted but displays incorrectly.
+
+**Duration:**
+
+```kotlin
+MetricsUnit.Duration.NANOSECOND
+MetricsUnit.Duration.MICROSECOND
+MetricsUnit.Duration.MILLISECOND  // most common for Android
+MetricsUnit.Duration.SECOND
+MetricsUnit.Duration.MINUTE
+MetricsUnit.Duration.HOUR
+MetricsUnit.Duration.DAY
+MetricsUnit.Duration.WEEK
+```
+
+**Information (data size):**
+
+```kotlin
+MetricsUnit.Information.BYTE
+MetricsUnit.Information.KILOBYTE
+MetricsUnit.Information.KIBIBYTE
+MetricsUnit.Information.MEGABYTE
+MetricsUnit.Information.MEBIBYTE
+MetricsUnit.Information.GIGABYTE
+MetricsUnit.Information.GIBIBYTE
+MetricsUnit.Information.TERABYTE
+```
+
+**Fraction:**
+
+```kotlin
+MetricsUnit.Fraction.RATIO    // 0.0 to 1.0
+MetricsUnit.Fraction.PERCENT  // 0.0 to 100.0
+```
+
+---
+
+## Batch Processing
+
+Metrics are batched and sent asynchronously:
+
+| Parameter        | Value                                                                      |
+| ---------------- | -------------------------------------------------------------------------- |
+| Flush delay      | 5 seconds after the first queued event                                     |
+| Max batch size   | 1,000 metrics per HTTP envelope                                            |
+| Max queue size   | 10,000 metrics (above this, new metrics are silently dropped)              |
+| Background flush | Yes — `AndroidMetricsBatchProcessor` flushes immediately on app background |
+
+---
+
+## Best Practices
+
+1. **Use consistent key names** — metric names should be `snake_case.namespaced`, e.g.
+   `checkout.duration` not `checkoutDuration`
+2. **Use `MetricsUnit.*` constants** — custom strings render incorrectly in the UI
+3. **Pass `null` unit for dimensionless metrics** — don’t leave unit as an empty string
+4. **Use attributes for dimensions** — prefer
+   `Sentry.metrics().count("api.call", 1.0, null, paramsWithEndpointAttr)` over separate
+   metric keys per endpoint
+5. **Use `beforeSend` to drop debug metrics in production** — avoids quota usage and
+   noise
+6. **Counter vs. Distribution** — use Counter for event occurrences (how many times),
+   Distribution for measurements (how long, how large)
+7. **Gauge for instantaneous state** — gauges are best for values that fluctuate: queue
+   depth, connection pool size, active sessions
+8. **Avoid high-cardinality attribute values** — user IDs, UUIDs, or timestamps as
+   attribute values create unbounded series in the Sentry backend
+
+---
+
+## Troubleshooting
+
+| Issue                                  | Solution                                                                                                                                          |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Metrics not appearing in Sentry        | Verify SDK ≥ 8.30.0; check that metrics were not disabled via `options.metrics.setEnabled(false)` or manifest `io.sentry.metrics.enabled = false` |
+| `set()` method not found               | The Set type does not exist in this SDK — only Counter, Distribution, and Gauge are available                                                     |
+| Metrics silently dropped               | Queue is capped at 10,000 events; use `beforeSend` to filter high-volume metrics                                                                  |
+| Unit renders incorrectly in Sentry UI  | Only `MetricsUnit.*` constants are supported; passing arbitrary strings is not                                                                    |
+| `beforeSend` dropping too many metrics | Ensure the return is `metric` (not `null`) for events you want to keep; a null return drops the event                                             |
+| Metrics data delayed by ~5s            | Expected — the batch processor holds events for 5 seconds before flushing                                                                         |
+| High memory on metrics-heavy screens   | Metrics are in-memory until flushed; avoid extremely high burst rates on low-memory devices                                                       |

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

@@ -0,0 +1,397 @@
+# Profiling — Sentry Android SDK
+
+> **Minimum SDK:** `io.sentry:sentry-android` ≥ 7.0.0 for transaction-based profiling
+> `io.sentry:sentry-android` ≥ 8.7.0 for continuous/UI profiling (recommended)
+> **Requirement:** Profiling requires tracing to be enabled.
+> Only transactions sampled for tracing can be profiled.
+> **Platform requirement:** Android API 22+ (silently disabled on older devices)
+
+Android profiling samples the call stack at ~101 Hz using
+`Debug.startMethodTracingSampling()` to surface hot code paths and slow functions.
+Profiles are attached to transactions and visible as flame graphs in Sentry.
+
+---
+
+## Table of Contents
+
+1. [How Profiling Works](#1-how-profiling-works)
+2. [Continuous / UI Profiling (Recommended)](#2-continuous--ui-profiling-recommended)
+3. [Transaction-Based Profiling (Legacy)](#3-transaction-based-profiling-legacy)
+4. [Choosing a Mode](#4-choosing-a-mode)
+5. [What Data Is Captured](#5-what-data-is-captured)
+6. [Performance Overhead](#6-performance-overhead)
+7. [Configuration Reference](#7-configuration-reference)
+8. [Known Limitations](#8-known-limitations)
+9. [Troubleshooting](#9-troubleshooting)
+
+---
+
+## 1. How Profiling Works
+
+```
+Transaction starts (sampled)
+  │
+  ├── Profiler starts: Debug.startMethodTracingSampling(file, 3MB, ~9901 μs)
+  │     ├── Samples JS/Kotlin/Java call stack at ~101 Hz
+  │     └── Writes binary trace to local file
+  │
+  ├── Transaction body executes
+  │     ├── Your code: Kotlin/Java frames
+  │     ├── Auto-instrumented spans (OkHttp, SQLite, etc.)
+  │     └── Collected: frames_slow, frames_frozen, screen_frame_rate
+  │
+  └── Transaction finishes
+        ├── Profiler stops: Debug.stopMethodTracing()
+        ├── Profile data deserialized into ProfilingTraceData
+        └── Attached to transaction envelope → uploaded to Sentry
+```
+
+### Sampling relationship
+
+`profilesSampleRate` is **relative to `tracesSampleRate`** — not to all transactions:
+
+```
+All transactions
+    └─ × tracesSampleRate  → Traced transactions
+              └─ × profilesSampleRate → Profiled transactions
+```
+
+Example: `tracesSampleRate = 0.2` + `profilesSampleRate = 0.5` → 10% of all transactions
+are profiled.
+
+---
+
+## 2. Continuous / UI Profiling (Recommended)
+
+Available since SDK 8.7.0. Profiles the entire app session (or only during active
+traces) rather than individual transactions.
+No 30-second hard cap.
+
+### Setup
+
+```kotlin
+import io.sentry.ProfileLifecycle
+import io.sentry.android.core.SentryAndroid
+
+SentryAndroid.init(this) { options ->
+    options.dsn = "YOUR_DSN"
+
+    // Tracing is required for TRACE lifecycle; optional for MANUAL
+    options.tracesSampleRate = 1.0
+
+    // Fraction of app sessions to profile continuously (evaluated once per session)
+    // 1.0 = all sessions — development/testing only
+    options.profileSessionSampleRate = 1.0
+
+    // TRACE: profile starts/stops automatically with root spans
+    // MANUAL: you call Sentry.startProfiler() / Sentry.stopProfiler()
+    options.profileLifecycle = ProfileLifecycle.TRACE
+
+    // MANUAL lifecycle only: start profiling from the very first frame
+    // options.isProfilingStartOnAppStart = true
+}
+```
+
+### `TRACE` lifecycle
+
+Profiler starts automatically when the first **sampled root span** begins, and stops
+when all root spans finish.
+No code changes needed beyond the options above.
+
+```
+App launches
+  └─ First traced transaction starts → profiler starts
+       ├─ Activity load transaction
+       ├─ User taps → another transaction
+       └─ All transactions finish → profiler stops
+           └─ Profile chunks emitted every 60 s
+```
+
+### `MANUAL` lifecycle
+
+You control start/stop explicitly.
+Does **not** require tracing.
+
+```kotlin
+import io.sentry.Sentry
+
+// @ApiStatus.Experimental — API may change
+Sentry.startProfiler()
+
+// ... do work you want to profile ...
+
+Sentry.stopProfiler()
+```
+
+> **Note:** `startProfiler()` and `stopProfiler()` are `@ApiStatus.Experimental`. Pin
+> your SDK version if API stability matters.
+
+### Profile chunks
+
+Continuous profiling emits profile data in 60-second rolling chunks.
+Each chunk is a separate envelope item correlated to active transactions via
+`profilerId`:
+
+```
+Session start  → profilerId generated (shared across all chunks)
+Every 60 s     → ProfileChunk(profilerId, chunkId, frames) uploaded
+Each transaction → contexts.profile.profiler_id = profilerId (links tx → profile)
+```
+
+---
+
+## 3. Transaction-Based Profiling (Legacy)
+
+Available since SDK 7.0.0. Profiles are scoped to individual sampled transactions with a
+30-second hard cap.
+
+### Setup
+
+```kotlin
+SentryAndroid.init(this) { options ->
+    options.dsn = "YOUR_DSN"
+
+    // Both must be set — profiling is relative to tracing
+    options.tracesSampleRate = 1.0
+    options.profilesSampleRate = 1.0  // 1.0 = profile all traced transactions
+
+    // Or: dynamic profiling sampler
+    // options.profilesSampler = ProfilesSamplerCallback { ctx ->
+    //     if (ctx.transactionContext.name.contains("Checkout")) 1.0 else 0.1
+    // }
+}
+```
+
+Java equivalent:
+
+```java
+options.setTracesSampleRate(1.0);
+options.setProfilesSampleRate(1.0);
+```
+
+### 30-second hard cap
+
+Transaction profiling uses `Debug.startMethodTracingSampling()` which is limited to 30
+seconds. Profiles for transactions longer than 30 s are automatically truncated:
+
+```
+Android SDK constants:
+  BUFFER_SIZE_BYTES    = 3_000_000  (3 MB ring buffer)
+  PROFILING_TIMEOUT_MILLIS = 30_000 (30 s hard cap)
+  Sampling interval    ≈ 9,901 μs   (101 Hz)
+```
+
+> **This is the primary reason to prefer continuous profiling.** Transactions that
+> exceed 30 s (e.g., long-running background work) have incomplete profiles in the
+> transaction-based mode.
+
+### Mutual exclusivity
+
+Setting `profilesSampleRate` (even to `0.0`) disables continuous profiling.
+The two modes cannot be used simultaneously:
+
+```kotlin
+// ✅ Continuous profiling only
+options.profileSessionSampleRate = 0.5   // set this
+// options.profilesSampleRate not set
+
+// ✅ Transaction profiling only (legacy)
+options.profilesSampleRate = 0.5         // set this
+// options.profileSessionSampleRate not set
+
+// ❌ Both set — continuous profiling silently disabled
+options.profilesSampleRate = 0.5
+options.profileSessionSampleRate = 0.5   // ignored
+```
+
+---
+
+## 4. Choosing a Mode
+
+|                        | Continuous / UI Profiling                     | Transaction-Based (Legacy)               |
+| ---------------------- | --------------------------------------------- | ---------------------------------------- |
+| **SDK version**        | ≥ 8.7.0                                       | ≥ 7.0.0                                  |
+| **Duration limit**     | None (60 s chunks)                            | 30 s hard cap                            |
+| **Tracing required**   | `TRACE` lifecycle: yes. `MANUAL`: no          | Yes                                      |
+| **Overhead**           | Higher (always sampling)                      | Lower (transaction-gated)                |
+| **Recommended for**    | All new projects                              | Existing projects not yet on 8.7+        |
+| **App start coverage** | ✅ `isProfilingStartOnAppStart = true`        | ❌ Profile starts with first transaction |
+| **API stability**      | `startProfiler/stopProfiler` are experimental | Stable                                   |
+
+**Choose continuous profiling** unless you are constrained to SDK < 8.7.0 or need to
+minimize profiling overhead on low-end devices.
+
+---
+
+## 5. What Data Is Captured
+
+### In a profile
+
+| Data                   | Description                                         |
+| ---------------------- | --------------------------------------------------- |
+| **Call stack samples** | Java/Kotlin stack frames sampled at ~101 Hz         |
+| **Flame graph**        | Aggregated time-per-function view                   |
+| **Timeline**           | Stack samples correlated with transaction spans     |
+| **Thread info**        | Main thread, background threads, system threads     |
+| **Frame metrics**      | `frames_slow`, `frames_frozen`, `screen_frame_rate` |
+| **Function names**     | Readable names require ProGuard mapping upload      |
+
+### What profiles are linked to
+
+Each profile chunk (continuous) or profile (transaction-based) is correlated with
+transactions via `profilerId`. In the Sentry UI you can:
+
+- View flame graph alongside the transaction’s span waterfall
+- Identify which functions executed during slow spans
+- Click from a slow span to the corresponding stack samples
+
+### What is NOT captured
+
+- Memory allocations (use Android Studio Memory Profiler)
+- Network traffic details (captured separately by OkHttp spans)
+- GPU rendering details (slow/frozen frames are a separate measurement)
+
+---
+
+## 6. Performance Overhead
+
+Profiling adds CPU overhead.
+`Debug.startMethodTracingSampling()` uses sampling (not full instrumentation), which
+keeps overhead lower than full instrumentation profilers.
+
+| Factor                              | Impact                                                   |
+| ----------------------------------- | -------------------------------------------------------- |
+| Transaction-based profiling         | Low-medium — only active during traced transactions      |
+| Continuous (`TRACE` lifecycle)      | Medium — always running while any transaction is active  |
+| Continuous (`MANUAL` lifecycle)     | Higher — runs from `startProfiler()` to `stopProfiler()` |
+| Low-end Android devices (< 4GB RAM) | More significant — test on representative devices        |
+
+**Recommendations:**
+
+- Use `profilesSampleRate = 1.0` or `profileSessionSampleRate = 1.0` **only** in
+  development/testing
+- In production: keep `profilesSampleRate ≤ 0.1` or `profileSessionSampleRate ≤ 0.1`
+- On low-end devices: reduce to `0.01`–`0.05`
+- Use `TRACE` lifecycle instead of `MANUAL` to gate profiling to active transactions
+
+---
+
+## 7. Configuration Reference
+
+### `SentryAndroid.init()` — profiling options
+
+```kotlin
+SentryAndroid.init(this) { options ->
+    // ── Required: tracing ────────────────────────────────────────────────
+    options.tracesSampleRate = 0.2       // required for TRACE lifecycle and transaction profiling
+
+    // ── Continuous profiling (recommended, SDK ≥ 8.7.0) ──────────────────
+    options.profileSessionSampleRate = 0.1          // 10% of sessions profiled
+    options.profileLifecycle = ProfileLifecycle.TRACE  // or MANUAL
+    options.isProfilingStartOnAppStart = false       // MANUAL only: start from first frame
+
+    // ── Transaction-based profiling (legacy) ──────────────────────────────
+    // options.profilesSampleRate = 0.1              // mutually exclusive with continuous
+    // options.profilesSampler = ProfilesSamplerCallback { ctx -> 0.1 }
+}
+```
+
+### `AndroidManifest.xml` — profiling keys
+
+| Key                                              | Type    | Default    | Description                         |
+| ------------------------------------------------ | ------- | ---------- | ----------------------------------- |
+| `io.sentry.traces.profiling.sample-rate`         | Float   | `null`     | Transaction profiling rate (legacy) |
+| `io.sentry.traces.profiling.session-sample-rate` | Float   | `null`     | Continuous profiling session rate   |
+| `io.sentry.traces.profiling.lifecycle`           | String  | `"manual"` | `"manual"` or `"trace"`             |
+| `io.sentry.traces.profiling.start-on-app-start`  | Boolean | `false`    | Auto-start profiler at app launch   |
+
+Via manifest (continuous profiling):
+
+```xml
+<meta-data android:name="io.sentry.traces.profiling.session-sample-rate" android:value="0.1" />
+<meta-data android:name="io.sentry.traces.profiling.lifecycle" android:value="trace" />
+```
+
+### `ProfileLifecycle` enum
+
+| Value    | Profiler starts          | Profiler stops          | Requires tracing |
+| -------- | ------------------------ | ----------------------- | ---------------- |
+| `TRACE`  | First sampled root span  | All root spans finished | Yes              |
+| `MANUAL` | `Sentry.startProfiler()` | `Sentry.stopProfiler()` | No               |
+
+### Manual start/stop (MANUAL lifecycle only)
+
+```kotlin
+// @ApiStatus.Experimental
+Sentry.startProfiler()
+// ... work to profile ...
+Sentry.stopProfiler()
+```
+
+---
+
+## 8. Known Limitations
+
+### Android API minimum
+
+Profiling uses `Debug.startMethodTracingSampling()`, which requires API 21+; effective
+minimum is **API 22**. Silently disabled on older devices with no error or warning.
+
+### Transaction profiling: 30-second hard cap
+
+Profiles for transactions longer than 30 s are automatically truncated.
+The transaction itself continues normally, but the profile has missing data for anything
+after 30 s. Use continuous profiling to avoid this.
+
+### 3 MB ring buffer
+
+Transaction profiling uses a 3 MB buffer.
+Very high-frequency call stacks on low-memory devices may overflow the buffer, causing
+early profile termination.
+
+### ProGuard/R8 obfuscation
+
+Release builds with ProGuard/R8 enabled produce obfuscated frame names (e.g., `a.b()`,
+`c.d()`). Upload mapping files to see readable names:
+
+```kotlin
+// build.gradle.kts
+sentry {
+    autoUploadProguardMapping = true
+}
+```
+
+### Background transactions
+
+If a transaction is abandoned while the app is backgrounded, the profile may be
+truncated. `DEADLINE_EXCEEDED` transactions may not have complete profiles.
+
+### Continuous profiling API stability
+
+`Sentry.startProfiler()` and `Sentry.stopProfiler()` are `@ApiStatus.Experimental`. The
+`_experiments` config block used in some SDKs is **not** used in Android — use
+`options.profileSessionSampleRate`, `options.profileLifecycle`, and
+`options.isProfilingStartOnAppStart` directly.
+
+### Continuous profiling chunk duration
+
+Chunks are emitted on a fixed 60-second cycle (`MAX_CHUNK_DURATION_MILLIS = 60_000`).
+This is not configurable.
+
+---
+
+## 9. Troubleshooting
+
+| Issue                                        | Likely cause                                                                          | Solution                                                                                   |
+| -------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| No profiles appearing                        | `profilesSampleRate` or `profileSessionSampleRate` not set, or `tracesSampleRate = 0` | Set both sample rates > 0; verify DSN is correct                                           |
+| Frame names appear obfuscated (`a.b`, `c.d`) | ProGuard/R8 mapping not uploaded                                                      | Configure `autoUploadProguardMapping = true` in the Sentry Gradle plugin                   |
+| Transaction profiling stops at 30 s          | Hard-coded 30 s cap                                                                   | Switch to continuous profiling (`profileSessionSampleRate`)                                |
+| Continuous profiling has no data             | `TRACE` lifecycle but no transactions sampled                                         | Verify `tracesSampleRate > 0`; check Sentry DSN and that events appear in Sentry           |
+| `startProfiler()` has no effect              | `TRACE` lifecycle selected instead of `MANUAL`                                        | Set `options.profileLifecycle = ProfileLifecycle.MANUAL` before calling `startProfiler()`  |
+| Profiling causes visible app slowdown        | Sample rate too high on low-end device                                                | Reduce `profilesSampleRate` or `profileSessionSampleRate` to ≤ 0.05 on low-end devices     |
+| `profileSessionSampleRate` ignored           | `profilesSampleRate` is also set                                                      | Remove `profilesSampleRate` — the two modes are mutually exclusive                         |
+| Profiles appear for some transactions only   | Expected — sample rate controls the fraction                                          | Increase rate if you want broader coverage                                                 |
+| App start not profiled                       | `isProfilingStartOnAppStart = false` (default)                                        | Set `options.isProfilingStartOnAppStart = true` with `MANUAL` lifecycle                    |
+| API < 22 device not profiling                | Silently disabled                                                                     | Profiling requires Android API 22+; check device API level                                 |
+| Profile data incomplete for long sessions    | 60 s chunk boundary                                                                   | Normal behavior — chunks are separate envelope items; use the trace waterfall to correlate |