@danieljvdm/dev-kit 1.0.2 → 2.0.0

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

@@ -0,0 +1,214 @@
+# Profiling — Sentry Flutter SDK
+
+> **Minimum SDK:** `sentry_flutter` ≥ **7.12.0**\
+> **Status:** ⚠️ **Alpha** — API may change without a major version bump\
+> **Platforms:** **iOS and macOS only** — Android, Web, Linux, Windows not supported
+
+Profiling samples the Dart and native call stack at regular intervals to surface hot
+code paths and slow functions.
+It requires tracing to be enabled — only transactions that are sampled can be profiled.
+
+---
+
+## Table of Contents
+
+1. [How Profiling Works](#1-how-profiling-works)
+2. [Basic Setup](#2-basic-setup)
+3. [What Data Is Captured](#3-what-data-is-captured)
+4. [Performance Overhead](#4-performance-overhead)
+5. [Configuration Reference](#5-configuration-reference)
+6. [Known Limitations](#6-known-limitations)
+7. [Troubleshooting](#7-troubleshooting)
+
+---
+
+## 1. How Profiling Works
+
+When a transaction is sampled for profiling, the SDK starts sampling the call stack at a
+fixed interval for the duration of that transaction.
+The profile is attached to the transaction and uploaded to Sentry alongside it.
+
+### 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.
+
+### Platform constraint
+
+The Flutter profiler hooks into the native iOS/macOS profiling infrastructure
+(equivalent to Instruments-style profiling).
+Android, Web, Linux, and Windows do **not** support profiling at the
+`profilesSampleRate` level — setting the option on those platforms has no effect.
+
+---
+
+## 2. Basic Setup
+
+### Minimum configuration
+
+```dart
+import 'package:flutter/widgets.dart';
+import 'package:sentry_flutter/sentry_flutter.dart';
+
+Future<void> main() async {
+  await SentryFlutter.init(
+    (options) {
+      options.dsn = 'YOUR_DSN';
+
+      // Tracing must be enabled — profiling only applies to traced transactions
+      options.tracesSampleRate = 1.0;
+
+      // profilesSampleRate is relative to tracesSampleRate
+      // 1.0 = profile every traced transaction (development / testing only)
+      options.profilesSampleRate = 1.0;
+    },
+    appRunner: () => runApp(MyApp()),
+  );
+}
+```
+
+### Recommended production configuration
+
+```dart
+await SentryFlutter.init(
+  (options) {
+    options.dsn = 'YOUR_DSN';
+
+    // Trace 20% of transactions
+    options.tracesSampleRate = 0.2;
+
+    // Profile 50% of those → 10% of all transactions profiled
+    options.profilesSampleRate = 0.5;
+  },
+  appRunner: () => runApp(MyApp()),
+);
+```
+
+> **Production guidance:** Profiling adds overhead.
+> Keep `profilesSampleRate` low in production.
+> Values above 0.1 are not recommended without explicit performance validation on your
+> minimum supported device.
+
+### Verifying profiles appear in Sentry
+
+1. Build and run on a **real iOS device** (not Simulator — see
+   [Known Limitations](#6-known-limitations))
+2. Trigger a user interaction that creates a transaction (e.g., navigate between screens
+   with `SentryNavigatorObserver`)
+3. Open Sentry → Performance → find the transaction → look for the **Profiling** tab in
+   the transaction detail
+
+---
+
+## 3. What Data Is Captured
+
+### In a profile
+
+| Data                   | Description                                                |
+| ---------------------- | ---------------------------------------------------------- |
+| **Call stack samples** | Sampled Dart + native stack frames at regular intervals    |
+| **Flame graph**        | Aggregated view of time spent in each function             |
+| **Timeline**           | Stack samples over time, correlated with transaction spans |
+| **Thread info**        | Main isolate thread, background threads, native threads    |
+| **Function names**     | From Dart debug info + native debug symbols                |
+
+### What profiles are linked to
+
+Each profile is attached to the transaction that triggered it.
+In the Sentry UI you can:
+
+- View the flame graph alongside the transaction’s span waterfall
+- Identify which functions were executing during slow spans
+
+### What is NOT captured
+
+- Memory allocations (use Xcode Instruments for that)
+- Network traffic details (captured separately via tracing spans)
+- UI rendering frames (slow/frozen frames are a separate tracing metric via
+  `SentryNavigatorObserver`)
+
+---
+
+## 4. Performance Overhead
+
+Profiling adds CPU overhead during sampled transactions.
+The sampler uses a fixed-interval approach (not full instrumentation), which limits
+overhead but does not eliminate it.
+
+| Factor                             | Impact                                                            |
+| ---------------------------------- | ----------------------------------------------------------------- |
+| `profilesSampleRate: 1.0`          | Higher — every traced transaction is profiled                     |
+| `profilesSampleRate: 0.1`          | Low — only 10% of traced transactions profiled                    |
+| Real device (iPhone 12+)           | Minimal visible impact                                            |
+| Older devices (iPhone 8 and below) | Measurable impact — validate before enabling                      |
+| iOS Simulator                      | Works but results differ from device — don’t use for benchmarking |
+
+**Recommendations:**
+
+- Use `profilesSampleRate: 1.0` only in development/testing
+- In production, start at `profilesSampleRate: 0.05` and increase if needed
+- Always validate on your minimum supported iOS device before shipping
+
+---
+
+## 5. Configuration Reference
+
+### `SentryFlutter.init` options
+
+| Option               | Type           | Default | Description                                                                                        |
+| -------------------- | -------------- | ------- | -------------------------------------------------------------------------------------------------- |
+| `profilesSampleRate` | `double` (0–1) | `null`  | Fraction of _traced_ transactions to also profile. Relative to `tracesSampleRate`. iOS/macOS only. |
+| `tracesSampleRate`   | `double` (0–1) | `null`  | Required for profiling. Fraction of transactions to trace.                                         |
+| `tracesSampler`      | `function`     | `null`  | Dynamic trace sampling. Takes precedence over `tracesSampleRate` when set.                         |
+
+### Minimum version table
+
+| Feature              | Min SDK  | Platforms  |
+| -------------------- | -------- | ---------- |
+| `profilesSampleRate` | `7.12.0` | iOS, macOS |
+
+---
+
+## 6. Known Limitations
+
+- **iOS and macOS only.** Android, Web, Linux, and Windows are **not supported**. The
+  option is silently ignored on unsupported platforms.
+- **Alpha status.** The profiling API and behavior may change in future minor versions.
+  Pin your SDK version if stability matters for a critical workflow.
+- **Simulator accuracy.** iOS Simulator profiling does not reflect real device
+  characteristics. Always validate performance conclusions on real hardware.
+- **Tracing required.** Setting `profilesSampleRate` without a non-zero
+  `tracesSampleRate` has no effect — no transactions are sampled, so no profiles can be
+  generated.
+- **Obfuscation.** Dart obfuscated builds (common in release builds) will show
+  obfuscated Dart frame names unless you upload Dart symbol files via
+  `sentry_dart_plugin`. Configure the plugin to upload `.symbols` files on each release
+  build.
+- **No manual profiling API.** You cannot start/stop a profile programmatically —
+  profiling is transaction-scoped only and controlled entirely by `profilesSampleRate`.
+- **Background transactions.** If a transaction completes while the app is backgrounded,
+  the profile may be truncated or absent.
+
+---
+
+## 7. Troubleshooting
+
+| Issue                                                | Likely Cause                                                         | Solution                                                                                          |
+| ---------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| No profiles appearing in Sentry                      | `profilesSampleRate` not set, or `tracesSampleRate` is `0` or `null` | Set both to `> 0`. Verify DSN is correct and events appear in Sentry at all.                      |
+| Option is set but no profiles on Android             | Android is not supported                                             | Expected — profiling is iOS/macOS only in the Flutter SDK.                                        |
+| Dart frames show obfuscated names (e.g., `_f`, `_g`) | Release build without symbol upload                                  | Configure `sentry_dart_plugin` to upload Dart symbol files (`--obfuscate` + `--split-debug-info`) |
+| Native frames show as hex addresses                  | dSYM not uploaded                                                    | Configure the Sentry Xcode build phase to upload dSYMs, or use `sentry_dart_plugin`               |
+| Profiles appear only for some transactions           | Expected behavior                                                    | `profilesSampleRate` controls the fraction. Increase if you want broader coverage.                |
+| Profile flame graph shows “unknown” functions        | Missing both Dart symbols and dSYMs                                  | Upload both via `sentry_dart_plugin` and the Xcode build phase                                    |
+| Profiling not working on iOS Simulator               | Known limitation — Simulator profiling may not match device behavior | Validate on a real device. Simulator results are indicative only.                                 |
+| App performance degraded after enabling profiling    | `profilesSampleRate` too high                                        | Reduce `profilesSampleRate`; test on your minimum supported device                                |
+| SDK crashes on startup with profiling enabled        | SDK version < 7.12.0                                                 | Upgrade `sentry_flutter` to ≥ 7.12.0                                                              |

package/skills/sentry/references/sdks/flutter/session-replay.md

@@ -0,0 +1,308 @@
+# Session Replay — Sentry Flutter SDK
+
+> **Minimum SDK:** `sentry_flutter` ≥ **9.0.0**\
+> **Platforms:** **iOS and Android only** — Web, macOS, Linux, Windows not supported\
+> **Frame rate:** ~**1 frame per second** (screenshot-based capture, not DOM recording)
+
+Flutter Session Replay captures a visual record of user sessions as a compressed
+sequence of screenshots, combined with breadcrumbs, traces, and error context.
+It works differently from web replay — understanding this prevents surprises.
+
+---
+
+## Table of Contents
+
+1. [How Flutter Replay Differs from Web Replay](#1-how-flutter-replay-differs-from-web-replay)
+2. [Basic Setup](#2-basic-setup)
+3. [Sample Rates](#3-sample-rates)
+4. [Privacy and Masking](#4-privacy-and-masking)
+5. [What the Replay UI Shows](#5-what-the-replay-ui-shows)
+6. [Session Lifecycle](#6-session-lifecycle)
+7. [Performance Overhead](#7-performance-overhead)
+8. [Configuration Reference](#8-configuration-reference)
+9. [Known Limitations](#9-known-limitations)
+10. [Troubleshooting](#10-troubleshooting)
+
+---
+
+## 1. How Flutter Replay Differs from Web Replay
+
+| Dimension             | Web Session Replay                     | Flutter Session Replay                       |
+| --------------------- | -------------------------------------- | -------------------------------------------- |
+| **Recording method**  | DOM serialization (HTML/CSS snapshots) | **Screenshot-based** (widget tree snapshots) |
+| **Frame rate**        | Variable (mutation-driven)             | **~1 frame per second**                      |
+| **Text in replay**    | ✅ Selectable, searchable              | ❌ Pixel-only — text is in screenshots       |
+| **CSS inspection**    | ✅ Available                           | ❌ Not available                             |
+| **Privacy mechanism** | CSS-based DOM masking                  | **Widget-level pixel masking**               |
+| **Rage clicks**       | ✅ Detected                            | ❌ Not supported                             |
+| **Touch recording**   | Full pointer events                    | Tap breadcrumbs only                         |
+| **Scroll positions**  | ✅ Precise                             | ⚠️ Approximate (from screenshots)            |
+
+---
+
+## 2. Basic Setup
+
+Flutter Session Replay is built into `sentry_flutter` — no separate package is needed.
+Wrap your root widget with `SentryWidget` (required for widget-tree privacy masking):
+
+```dart
+import 'package:flutter/widgets.dart';
+import 'package:sentry_flutter/sentry_flutter.dart';
+
+Future<void> main() async {
+  await SentryFlutter.init(
+    (options) {
+      options.dsn = 'YOUR_DSN';
+
+      // Session replay sampling
+      options.replay.sessionSampleRate = 0.1;   // 10% of all sessions recorded
+      options.replay.onErrorSampleRate = 1.0;   // 100% when an error occurs
+    },
+    appRunner: () => runApp(
+      SentryWidget(   // required — wraps the app for screenshot capture
+        child: MyApp(),
+      ),
+    ),
+  );
+}
+```
+
+> **During development:** Use `options.replay.sessionSampleRate = 1.0` so every session
+> is recorded. Lower it before shipping to production.
+
+---
+
+## 3. Sample Rates
+
+### `replay.sessionSampleRate`
+
+Records the **entire user session** from SDK initialization / app foreground entry.
+
+- Range: `0.0` – `1.0`
+- Captures everything from session start
+
+### `replay.onErrorSampleRate`
+
+Only activates when an **error occurs**. The SDK maintains a rolling pre-error buffer
+and captures that buffer plus everything after the error.
+
+- Range: `0.0` – `1.0`
+- Gives you context for what led up to the error
+
+### Recommended production values
+
+| Strategy                       | `sessionSampleRate` | `onErrorSampleRate` |
+| ------------------------------ | ------------------- | ------------------- |
+| Errors-only (minimal overhead) | `0`                 | `1.0`               |
+| Balanced                       | `0.05`              | `1.0`               |
+| High visibility                | `0.1`               | `1.0`               |
+
+---
+
+## 4. Privacy and Masking
+
+> ⚠️ **Production warning:** Always verify your masking config before enabling in
+> production. The SDK masks aggressively by default, but any customizations require
+> thorough testing with your actual app UI. If you discover unmasked PII, disable
+> Session Replay until resolved.
+
+### Default behavior
+
+The SDK **aggressively masks all text, images, and user input by default**:
+
+| Widget type                        | Default behavior     |
+| ---------------------------------- | -------------------- |
+| `Text`, `RichText`, `EditableText` | ✅ Masked by default |
+| `Image` (including asset images)   | ✅ Masked by default |
+| `TextFormField`, `TextField`       | ✅ Masked by default |
+
+Masked areas are replaced with a filled block using a neutral color.
+
+### Privacy configuration options
+
+Configure masking in `SentryFlutter.init`:
+
+```dart
+await SentryFlutter.init(
+  (options) {
+    options.dsn = 'YOUR_DSN';
+    options.replay.sessionSampleRate = 0.1;
+    options.replay.onErrorSampleRate = 1.0;
+
+    // Masking options — all true by default
+    options.privacy.maskAllText = true;      // mask Text, RichText, EditableText
+    options.privacy.maskAllImages = true;    // mask Image widgets
+    options.privacy.maskAssetImages = true;  // mask asset bundle images
+  },
+  appRunner: () => runApp(SentryWidget(child: MyApp())),
+);
+```
+
+### Mask specific widget types
+
+```dart
+// Mask all IconButton widgets (masked by the widget type)
+options.privacy.mask<IconButton>();
+
+// Unmask Image widgets (show images in replay)
+options.privacy.unmask<Image>();
+```
+
+### Custom masking logic per widget instance
+
+```dart
+options.privacy.maskCallback<Text>(
+  (Element element, Text widget) {
+    // Mask only text containing 'secret'
+    if (widget.data?.contains('secret') ?? false) {
+      return SentryMaskingDecision.mask;
+    }
+    return SentryMaskingDecision.continueProcessing;
+  },
+);
+```
+
+### Disable all masking
+
+Only do this if your app contains absolutely no sensitive data:
+
+```dart
+options.privacy.maskAllText = false;
+options.privacy.maskAllImages = false;
+options.privacy.maskAssetImages = false;
+```
+
+### Third-party widget masking
+
+The SDK cannot automatically detect or mask third-party widgets.
+You must register them explicitly:
+
+```dart
+// Example: mask a map widget from a third-party package
+options.privacy.mask<FlutterMap>();
+
+// Example: mask a video player widget
+options.privacy.mask<VideoPlayer>();
+```
+
+---
+
+## 5. What the Replay UI Shows
+
+| Panel           | Content                                                   |
+| --------------- | --------------------------------------------------------- |
+| **Video**       | Compressed screenshot sequence at ~1 fps                  |
+| **Breadcrumbs** | User taps, navigation events, app lifecycle transitions   |
+| **Timeline**    | Scrubbable view with event markers                        |
+| **Network**     | HTTP requests made during the session                     |
+| **Errors**      | All errors in the session linked to Sentry issues         |
+| **Tags**        | OS version, device specs, release, user info, custom tags |
+| **Trace**       | All distributed traces during the replay session          |
+
+### Touch / gesture recording
+
+Touch interactions are recorded as **breadcrumb events** (discrete tap events), not raw
+gesture streams:
+
+- ✅ Captured: Tap position, tapped widget, timestamp
+- ❌ Not captured: Swipe paths, gesture velocity, multi-touch sequences
+
+---
+
+## 6. Session Lifecycle
+
+| Event                                           | Effect                        |
+| ----------------------------------------------- | ----------------------------- |
+| SDK initializes / app enters foreground         | New session starts            |
+| App goes to background                          | Session pauses                |
+| App returns to foreground within **30 seconds** | Same session continues        |
+| App returns to foreground after **30+ seconds** | New session starts            |
+| Session reaches **60 minutes**                  | Session terminates            |
+| App crashes / closes in background              | Session terminates abnormally |
+
+The `onErrorSampleRate` mode keeps a pre-error buffer in memory.
+When an error occurs, this buffer plus the subsequent recording is captured and sent.
+
+---
+
+## 7. Performance Overhead
+
+Session Replay adds CPU and memory overhead from periodic screenshot capture and
+compression.
+
+| Metric            | With Replay  | Notes                          |
+| ----------------- | ------------ | ------------------------------ |
+| CPU               | +5–10%       | During active recording        |
+| Memory            | +15–25 MB    | Screenshot buffer              |
+| FPS impact        | -1 to -2 fps | Minimal on modern devices      |
+| Network bandwidth | ~7–10 KB/s   | Compressed screenshot segments |
+
+### Reducing performance impact
+
+```dart
+options.replay.sessionSampleRate = 0.05;  // lower session recording rate
+options.replay.onErrorSampleRate = 1.0;   // keep error capture at 100%
+```
+
+Consider using `onErrorSampleRate` only (set `sessionSampleRate` to `0`) for the lowest
+overhead while retaining the most valuable replay data.
+
+---
+
+## 8. Configuration Reference
+
+### `options.replay` settings
+
+| Option                     | Type           | Default | Description                                                  |
+| -------------------------- | -------------- | ------- | ------------------------------------------------------------ |
+| `replay.sessionSampleRate` | `double` (0–1) | `0`     | Fraction of all sessions to record from start                |
+| `replay.onErrorSampleRate` | `double` (0–1) | `0`     | Fraction of error sessions to record (with pre-error buffer) |
+
+### `options.privacy` settings
+
+| Option                      | Type   | Default | Description                                 |
+| --------------------------- | ------ | ------- | ------------------------------------------- |
+| `privacy.maskAllText`       | `bool` | `true`  | Mask Text, RichText, EditableText widgets   |
+| `privacy.maskAllImages`     | `bool` | `true`  | Mask Image widgets                          |
+| `privacy.maskAssetImages`   | `bool` | `true`  | Mask asset bundle images                    |
+| `privacy.mask<T>()`         | method | —       | Mask all instances of widget type T         |
+| `privacy.unmask<T>()`       | method | —       | Unmask all instances of widget type T       |
+| `privacy.maskCallback<T>()` | method | —       | Custom masking decision per widget instance |
+
+### Version requirements
+
+| Feature                          | Min SDK |
+| -------------------------------- | ------- |
+| Session Replay (iOS + Android)   | `9.0.0` |
+| `options.replay.*` configuration | `9.0.0` |
+| `options.privacy.*` masking      | `9.0.0` |
+
+---
+
+## 9. Known Limitations
+
+| Limitation                    | Details                                                                                                                   |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| iOS and Android only          | Web, macOS, Linux, and Windows are **not supported**. Replay configuration is silently ignored on unsupported platforms.  |
+| ~1 fps frame rate             | Not suitable for high-frequency UI debugging. Best for understanding flow and identifying the screen state during errors. |
+| Text is not selectable        | Screenshots capture pixels only — you cannot copy text from a replay.                                                     |
+| No swipe/gesture paths        | Only discrete tap events are recorded as breadcrumbs. Gesture trajectories are not captured.                              |
+| Third-party widget masking    | Must be registered manually via `options.privacy.mask<WidgetType>()` — the SDK cannot auto-detect foreign widget types.   |
+| Pre-error buffer is in-memory | Low-memory devices may have a shorter effective pre-error buffer.                                                         |
+| No DOM inspection             | Unlike web replay, you cannot inspect the widget tree state at a given frame — only the screenshot is available.          |
+
+---
+
+## 10. Troubleshooting
+
+| Issue                                              | Solution                                                                                                                                 |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Replay not recording at all                        | Verify `options.replay.sessionSampleRate` or `options.replay.onErrorSampleRate` is `> 0`. Confirm `SentryWidget` wraps your root widget. |
+| Platform not supported                             | Expected — Flutter Session Replay is iOS and Android only. Check you’re building for a supported platform.                               |
+| All content masked after disabling masking         | Verify you’ve set `options.privacy.maskAllText = false` and `options.privacy.maskAllImages = false` before `appRunner` runs.             |
+| Third-party widget content visible despite masking | Register the widget type: `options.privacy.mask<ThirdPartyWidget>()`                                                                     |
+| High memory usage with replay enabled              | Lower `sessionSampleRate`; consider using `onErrorSampleRate` only (set `sessionSampleRate` to `0`)                                      |
+| Replay works in debug but not in production        | Verify sample rates are non-zero in your production `SentryFlutter.init()` call; check DSN is correct for the environment                |
+| Pre-error buffer empty                             | Low memory device may have dropped the buffer. No workaround currently.                                                                  |
+| Replay sessions not linked to errors               | Ensure both `onErrorSampleRate > 0` and the SDK is initialized before the error occurs                                                   |
+| Tap events missing in replay                       | Confirm `SentryWidget` is wrapping the widget tree — it intercepts gesture events to record taps                                         |