@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/sdks/elixir/tracing.md

@@ -0,0 +1,233 @@
+# Tracing — Sentry Elixir SDK
+
+> Minimum SDK: `sentry` v11.0.0+ (beta); v12.0.0+ for distributed tracing and LiveView
+> spans
+
+Tracing in the Elixir SDK is implemented via **OpenTelemetry**. Sentry ships three OTel
+components: a `SpanProcessor`, a `Sampler`, and a `Propagator`. These integrate with the
+OpenTelemetry Elixir ecosystem so you can use any OTel-compatible instrumentation
+library (Phoenix, Ecto, Finch, etc.)
+and have all spans forwarded to Sentry.
+
+## Configuration
+
+### Dependencies
+
+```elixir
+# mix.exs
+defp deps do
+  [
+    {:sentry, "~> 12.0"},
+    {:finch, "~> 0.21"},
+    # OpenTelemetry core
+    {:opentelemetry, "~> 1.5"},
+    {:opentelemetry_api, "~> 1.4"},
+    {:opentelemetry_exporter, "~> 1.0"},
+    {:opentelemetry_semantic_conventions, "~> 1.27"},
+    # Optional: Phoenix and Ecto auto-instrumentation
+    {:opentelemetry_phoenix, "~> 2.0"},
+    {:opentelemetry_ecto, "~> 1.2"}
+  ]
+end
+```
+
+### Sentry config
+
+Any non-nil value for `:traces_sample_rate` enables tracing.
+Start with `1.0` for development, lower for production:
+
+```elixir
+# config/config.exs
+config :sentry,
+  dsn: System.get_env("SENTRY_DSN"),
+  traces_sample_rate: 1.0     # lower to 0.1 in high-traffic production
+```
+
+### OpenTelemetry config
+
+Wire Sentry’s SpanProcessor and Sampler into the OTel pipeline:
+
+```elixir
+# config/config.exs
+config :opentelemetry,
+  span_processor: {Sentry.OpenTelemetry.SpanProcessor, []},
+  sampler: {Sentry.OpenTelemetry.Sampler, []}
+```
+
+### Distributed tracing (since v12.0.0)
+
+Enable Sentry’s propagator to inject and extract `sentry-trace` and `baggage` headers:
+
+```elixir
+# config/config.exs
+config :opentelemetry,
+  span_processor: {Sentry.OpenTelemetry.SpanProcessor, []},
+  sampler: {Sentry.OpenTelemetry.Sampler, []},
+  text_map_propagators: [
+    :trace_context,
+    :baggage,
+    Sentry.OpenTelemetry.Propagator
+  ]
+```
+
+> **Note:** Add `Sentry.OpenTelemetry.Propagator` **after** the standard
+> `:trace_context` and `:baggage` propagators.
+> It reads and writes the Sentry-specific `sentry-trace` and `baggage` headers so spans
+> from Elixir connect to browser and backend spans from other Sentry SDKs.
+
+## Sampling
+
+### Uniform sample rate
+
+```elixir
+config :sentry,
+  traces_sample_rate: 0.1   # 10% of all root spans
+```
+
+### Custom sampler function
+
+Use `:traces_sampler` to apply per-operation logic.
+Overrides `:traces_sample_rate` when set:
+
+```elixir
+config :sentry,
+  traces_sampler: fn sampling_context ->
+    case sampling_context.transaction_context.op do
+      "http.server" -> 0.1           # 10% of HTTP requests
+      "db.query"    -> 0.01          # 1% of DB queries
+      _             -> false         # drop everything else
+    end
+  end
+```
+
+### Drop specific transaction names
+
+Use the built-in `drop` option of `Sentry.OpenTelemetry.Sampler`:
+
+```elixir
+config :opentelemetry,
+  sampler: {Sentry.OpenTelemetry.Sampler, [drop: ["health_check", "liveness_check"]]}
+```
+
+## Phoenix Auto-Instrumentation
+
+`opentelemetry_phoenix` automatically creates spans for each Phoenix request.
+Setup in `Application.start/2`:
+
+```elixir
+# lib/my_app/application.ex
+def start(_type, _args) do
+  Logger.add_handlers(:my_app)
+  OpentelemetryPhoenix.setup()    # instruments Phoenix controllers and LiveView (requires opentelemetry_phoenix)
+  OpentelemetryEcto.setup([:my_app, :repo])   # instruments Ecto queries (requires opentelemetry_ecto)
+
+  children = [
+    MyApp.Repo,
+    MyAppWeb.Endpoint
+  ]
+
+  Supervisor.start_link(children, strategy: :one_for_one)
+end
+```
+
+## How Spans Map to Sentry
+
+| OTel span type                                            | Sentry object                                |
+| --------------------------------------------------------- | -------------------------------------------- |
+| Root span (no local parent)                               | `Transaction`                                |
+| Child span (has local parent)                             | `Span` within that transaction               |
+| Distributed span (remote parent, HTTP server or LiveView) | New `Transaction` root (linked via trace ID) |
+
+Root spans are created when:
+
+- An HTTP request arrives with no `sentry-trace` parent (or sampling says yes)
+- A LiveView mounts (since v12.0.0)
+- You manually start a root-level OTel span
+
+## Custom Spans
+
+Use the standard OpenTelemetry API for custom instrumentation:
+
+```elixir
+require OpenTelemetry.Tracer, as: Tracer
+
+def process_order(order_id) do
+  Tracer.with_span "process_order", %{attributes: [{"order.id", order_id}]} do
+    # All work done inside this block is a child span
+    validate_order(order_id)
+    charge_payment(order_id)
+    send_confirmation(order_id)
+  end
+end
+
+def validate_order(order_id) do
+  Tracer.with_span "validate_order", %{kind: :internal} do
+    # Nested child span
+    # ...
+  end
+end
+```
+
+### Setting span attributes
+
+```elixir
+Tracer.with_span "db.query" do
+  Tracer.set_attributes([
+    {"db.system", "postgresql"},
+    {"db.statement", "SELECT * FROM orders WHERE id = $1"},
+    {"db.rows_affected", 1}
+  ])
+  # run query
+end
+```
+
+### Propagating context through async code
+
+OTel context must be explicitly propagated when crossing process boundaries:
+
+```elixir
+# Capture current context before spawning
+ctx = OpenTelemetry.Ctx.get_current()
+
+Task.start(fn ->
+  # Attach parent context in the new process
+  OpenTelemetry.Ctx.attach(ctx)
+
+  Tracer.with_span "async.work" do
+    perform_work()
+  end
+end)
+```
+
+## OpenTelemetry Components Reference
+
+| Module                               | OTel behaviour              | Purpose                                                       |
+| ------------------------------------ | --------------------------- | ------------------------------------------------------------- |
+| `Sentry.OpenTelemetry.SpanProcessor` | `:otel_span_processor`      | Converts finished OTel spans into Sentry transactions/spans   |
+| `Sentry.OpenTelemetry.Sampler`       | `:otel_sampler`             | Applies `traces_sample_rate` / `traces_sampler` to root spans |
+| `Sentry.OpenTelemetry.Propagator`    | `:otel_propagator_text_map` | Injects/extracts `sentry-trace` and `baggage` headers         |
+
+## Best Practices
+
+- Set `traces_sample_rate: 1.0` in development and `0.1–0.2` in production; adjust per
+  route with `traces_sampler`
+- Use the `drop:` option in `Sentry.OpenTelemetry.Sampler` to exclude health check
+  endpoints from tracing
+- Always call `OpentelemetryPhoenix.setup()` and `OpentelemetryEcto.setup/1` in
+  `Application.start/2` before the supervision tree starts
+- Propagate OTel context explicitly when spawning tasks or sending messages to other
+  processes
+- Add `Sentry.OpenTelemetry.Propagator` for distributed tracing across services —
+  without it, backend traces won’t link to browser Sentry events
+
+## Troubleshooting
+
+| Issue                         | Solution                                                                                                        |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| No transactions in Sentry     | Verify `traces_sample_rate` is set (non-nil); confirm `span_processor` is configured in `:opentelemetry` config |
+| Phoenix spans missing         | Call `OpentelemetryPhoenix.setup()` in `Application.start/2` before the supervision tree                        |
+| Ecto query spans missing      | Call `OpentelemetryEcto.setup([:my_app, :repo])` in `Application.start/2`                                       |
+| Distributed trace not linking | Add `Sentry.OpenTelemetry.Propagator` to `text_map_propagators`; requires v12.0.0+                              |
+| LiveView spans not appearing  | Requires v12.0.0+ and `opentelemetry_phoenix ~> 2.0`                                                            |
+| Context lost in async `Task`  | Capture `OpenTelemetry.Ctx.get_current()` before spawning; call `OpenTelemetry.Ctx.attach(ctx)` inside the task |
+| Too many DB spans             | Use `traces_sampler` to lower sample rate for `"db.query"` operations                                           |

package/skills/sentry/references/sdks/flutter/ecosystem-integrations.md

@@ -0,0 +1,70 @@
+# Ecosystem Integrations — Sentry Flutter SDK
+
+Add these packages alongside `sentry_flutter` for deeper instrumentation:
+
+### HTTP Clients
+
+**Standard `http` package** — built into `sentry_flutter`, no extra install:
+
+```dart
+import 'package:sentry/sentry.dart';
+
+// Wrap your http client
+final client = SentryHttpClient(
+  captureFailedRequests: true,
+  failedRequestStatusCodes: [SentryStatusCode.range(400, 599)],
+);
+try {
+  final response = await client.get(Uri.parse('https://api.example.com/users'));
+} finally {
+  client.close();
+}
+```
+
+**Dio** — install `sentry_dio`:
+
+```bash
+flutter pub add sentry_dio
+```
+
+```dart
+import 'package:dio/dio.dart';
+import 'package:sentry_dio/sentry_dio.dart';
+
+final dio = Dio();
+// Add your interceptors first, THEN addSentry() last
+dio.addSentry(
+  captureFailedRequests: true,
+  failedRequestStatusCodes: [SentryStatusCode.range(400, 599)],
+);
+```
+
+### Databases
+
+| Package          | Install                          | Setup                                                        |
+| ---------------- | -------------------------------- | ------------------------------------------------------------ |
+| `sentry_sqflite` | `flutter pub add sentry_sqflite` | `databaseFactory = SentrySqfliteDatabaseFactory();`          |
+| `sentry_drift`   | `flutter pub add sentry_drift`   | `.interceptWith(SentryQueryInterceptor(databaseName: 'db'))` |
+| `sentry_hive`    | `flutter pub add sentry_hive`    | Use `SentryHive` instead of `Hive`                           |
+| `sentry_isar`    | `flutter pub add sentry_isar`    | Use `SentryIsar.open()` instead of `Isar.open()`             |
+
+### Other
+
+| Package                         | Install                                         | Purpose                                            |
+| ------------------------------- | ----------------------------------------------- | -------------------------------------------------- |
+| `sentry_logging`                | `flutter pub add sentry_logging`                | Dart `logging` package → Sentry breadcrumbs/events |
+| `sentry_link`                   | `flutter pub add sentry_link`                   | GraphQL (gql, graphql_flutter, ferry) tracing      |
+| `sentry_supabase`               | `flutter pub add sentry_supabase`               | Supabase query tracing (SDK ≥9.9.0)                |
+| `sentry_firebase_remote_config` | `flutter pub add sentry_firebase_remote_config` | Feature flag tracking                              |
+| `sentry_file`                   | `flutter pub add sentry_file`                   | File I/O tracing via `.sentryTrace()` extension    |
+
+### State Management Patterns
+
+No official packages — wire Sentry via observer APIs:
+
+| Framework                   | Hook point                               | Pattern                                                                                                                           |
+| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| **BLoC/Cubit**              | `BlocObserver.onError`                   | `Sentry.captureException(error, stackTrace: stackTrace)` inside `onError`; set `Bloc.observer = SentryBlocObserver()` before init |
+| **Riverpod**                | `ProviderObserver.providerDidFail`       | Fires for `FutureProvider`/`StreamProvider` failures; wrap app with `ProviderScope(observers: [SentryProviderObserver()])`        |
+| **Provider/ChangeNotifier** | `try/catch` in `notifyListeners` callers | Manually call `Sentry.captureException(e, stackTrace: stack)` in catch blocks                                                     |
+| **GetX**                    | `GetMaterialApp.onError`                 | `GetMaterialApp(onError: (details) => Sentry.captureException(...))`                                                              |

package/skills/sentry/references/sdks/flutter/error-monitoring.md

@@ -0,0 +1,312 @@
+# Error Monitoring — Flutter SDK Reference
+
+> **Minimum SDK version:** `sentry_flutter` ≥ 7.0.0 (all features), ≥ 9.14.0 (tombstone,
+> trace sync) **Platforms:** All (Android, iOS, macOS, Linux, Windows, Web —
+> platform-specific caveats noted)
+
+## What’s Auto-Captured
+
+When `SentryFlutter.init()` runs, the SDK installs these handlers automatically:
+
+| Handler                               | Captures                                                         | Platforms                           |
+| ------------------------------------- | ---------------------------------------------------------------- | ----------------------------------- |
+| `FlutterError.onError`                | Widget build errors, rendering errors, gesture errors            | All                                 |
+| `PlatformDispatcher.instance.onError` | Uncaught Dart async errors (root zone)                           | All (Flutter ≥ 3.3)                 |
+| Android SDK (bundled)                 | Java/Kotlin JVM exceptions, NDK native crashes                   | Android                             |
+| iOS/macOS SDK (bundled)               | ObjC `NSException`, Swift errors, POSIX signals, Mach exceptions | iOS, macOS                          |
+| `WidgetsBindingObserver`              | App lifecycle breadcrumbs                                        | Linux, Windows, Web (no native SDK) |
+
+Silent framework errors (`FlutterErrorDetails.silent == true`) are excluded unless you
+opt in:
+
+```dart
+options.reportSilentFlutterErrors = true;
+```
+
+---
+
+## Manual Capture APIs
+
+### Capture Exception
+
+Always pass `stackTrace` — without it Sentry can’t show the correct call stack:
+
+```dart
+import 'package:sentry/sentry.dart';
+
+try {
+  await riskyOperation();
+} catch (e, stackTrace) {
+  await Sentry.captureException(e, stackTrace: stackTrace);
+}
+```
+
+With a one-off local scope (doesn’t affect subsequent events):
+
+```dart
+await Sentry.captureException(
+  e,
+  stackTrace: stackTrace,
+  withScope: (scope) {
+    scope.setTag('feature', 'checkout');
+    scope.setTag('step', 'payment');
+    scope.level = SentryLevel.fatal;
+    scope.setExtra('orderId', orderId);
+  },
+);
+```
+
+### Capture Message
+
+```dart
+await Sentry.captureMessage(
+  'Rate limit threshold exceeded',
+  level: SentryLevel.warning,
+);
+
+// Available levels:
+// SentryLevel.debug | info | warning | error | fatal
+```
+
+### Capture User Feedback
+
+```dart
+final eventId = await Sentry.captureException(e, stackTrace: st);
+
+await Sentry.captureFeedback(
+  SentryFeedback(
+    message: 'App froze after uploading the photo.',
+    contactEmail: 'user@example.com',
+    name: 'Jane Doe',
+    associatedEventId: eventId,
+  ),
+);
+```
+
+---
+
+## Scope — Enrich All Events
+
+### Global Scope (persists across events)
+
+```dart
+import 'package:sentry/sentry.dart';
+
+// Set user on login
+Sentry.configureScope((scope) => scope.setUser(SentryUser(
+  id: 'user-123',
+  username: 'jdoe',
+  email: 'jane@example.com',
+  name: 'Jane Doe',
+  data: {'subscription_tier': 'pro'},
+)));
+
+// Clear user on logout
+Sentry.configureScope((scope) => scope.setUser(null));
+
+// Tags — indexed, searchable (key max 32 chars, value max 200 chars)
+Sentry.configureScope((scope) {
+  scope.setTag('app.flavor', 'enterprise');
+  scope.setTag('locale', 'pt-BR');
+});
+
+// Contexts — non-searchable structured data (visible in Sentry UI)
+Sentry.configureScope((scope) => scope.setContexts('cart', {
+  'items_count': 3,
+  'total_usd': 149.99,
+}));
+
+// Attributes (SDK ≥9.9.0) — apply to logs, metrics, and spans too
+Sentry.setAttributes({'user_tier': SentryAttribute.string('premium')});
+Sentry.removeAttribute('user_tier');
+```
+
+### Scope Sync to Native (Android/iOS)
+
+When `options.enableScopeSync = true` (default), these methods sync to the native SDK
+layer so native crash reports include your Dart context:
+
+- `scope.setUser()` / `scope.setContexts()` / `scope.setTag()` / `scope.setExtra()`
+- `scope.addBreadcrumb()` / `scope.clearBreadcrumbs()`
+
+---
+
+## Breadcrumbs
+
+Manual breadcrumbs build an audit trail leading to each error:
+
+```dart
+Sentry.addBreadcrumb(Breadcrumb(
+  message: 'User tapped checkout button',
+  category: 'ui.action',
+  type: 'user',
+  level: SentryLevel.info,
+  data: {'screen': 'CartScreen', 'cart_total': 149.99},
+));
+```
+
+Filter or modify breadcrumbs before storage:
+
+```dart
+options.beforeBreadcrumb = (breadcrumb, hint) {
+  // Drop noisy analytics calls
+  if (breadcrumb.data?['url']?.contains('analytics') == true) {
+    return null; // null = drop
+  }
+  // Strip auth headers from HTTP breadcrumbs
+  if (breadcrumb.type == 'http') {
+    final data = Map<String, dynamic>.from(breadcrumb.data ?? {})
+      ..remove('Authorization');
+    return breadcrumb.copyWith(data: data);
+  }
+  return breadcrumb;
+};
+```
+
+Increase capacity if needed (default: 100):
+
+```dart
+options.maxBreadcrumbs = 150;
+```
+
+---
+
+## Event Filtering
+
+Drop or modify events before they’re sent:
+
+```dart
+options.beforeSend = (event, hint) async {
+  // Drop database connection errors (too noisy)
+  if (event.throwable is DatabaseConnectionException) return null;
+
+  // Group similar payment failures
+  if (event.throwable is PaymentException) {
+    event.fingerprint = ['payment-failure'];
+  }
+
+  // Strip server name for privacy
+  event.serverName = '';
+  return event;
+};
+```
+
+> ⚠️ `beforeSend` intercepts **Dart-layer events only**. Native crashes from Android NDK
+> or iOS bypass it.
+
+Error sampling (drop a fraction of errors — not recommended unless volume is very high):
+
+```dart
+options.sampleRate = 0.5; // send only 50% of errors
+```
+
+---
+
+## Isolate Error Capture
+
+Errors in non-root Dart isolates aren’t automatically captured.
+Forward them explicitly:
+
+```dart
+import 'dart:isolate';
+import 'package:sentry/sentry.dart';
+
+final isolate = await Isolate.spawn(myIsolateEntry, someData);
+isolate.addSentryErrorListener(); // forwards uncaught errors to Sentry
+```
+
+> ⚠️ Isolate errors are NOT captured on Web (no Isolate API in browser).
+
+---
+
+## Attachments
+
+Automatically attach screenshots and widget hierarchy to error events:
+
+```dart
+options.attachScreenshot = true;          // screenshot at time of error
+options.screenshotQuality = ScreenshotQuality.high; // full/high/medium/low
+options.attachViewHierarchy = true;       // JSON widget tree snapshot
+```
+
+Requires `SentryWidget(child: MyApp())` as the app root.
+Not available on Web.
+
+Attach files manually via scope:
+
+```dart
+import 'package:sentry/sentry_io.dart';
+
+final attachment = IoSentryAttachment.fromPath('/path/to/debug.log');
+Sentry.configureScope((scope) => scope.addAttachment(attachment));
+```
+
+---
+
+## Android Native Crash Options
+
+```dart
+// Android 12+ tombstone crash info via ApplicationExitInfo (SDK ≥9.14.0, opt-in)
+options.enableTombstone = true;
+
+// Sync Java/Kotlin scope to NDK
+options.enableNdkScopeSync = true; // default: true
+
+// Attach all threads to crash report
+options.attachThreads = true; // default: false
+
+// ANR detection
+options.anrEnabled = true;             // default: true
+options.anrTimeoutInterval = 5000;     // ms; increase if too many false positives
+```
+
+---
+
+## iOS/macOS Native Crash Options
+
+```dart
+// Watchdog termination (OOM kill) tracking
+options.enableWatchdogTerminationTracking = true; // default: true
+
+// Native HTTP failures independent of Dart client (SDK ≥9.11.0)
+options.captureNativeFailedRequests = true;
+```
+
+---
+
+## Release Health
+
+Session tracking is on by default — gives you crash-free user and session metrics in the
+Sentry dashboard:
+
+```dart
+// Disable if not needed
+options.enableAutoSessionTracking = false;
+
+// Tune session expiry (how long in background before a new session starts)
+options.autoSessionTrackingInterval = const Duration(seconds: 60); // default: 30s
+```
+
+Release is auto-set on iOS/Android as `"packageName@versionName+versionCode"`. Override
+if needed:
+
+```dart
+options.release = 'my-app@2.1.0+105';
+```
+
+---
+
+## Troubleshooting
+
+| Issue                                      | Solution                                                                                               |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| Events not appearing in Sentry             | Set `options.debug = true`, check Flutter console for SDK errors; verify DSN                           |
+| Stack traces unreadable                    | Build with `--obfuscate --split-debug-info` and upload with `sentry_dart_plugin`                       |
+| Native crashes not captured                | Confirm `enableNativeCrashHandling: true`; test in release mode (not debug)                            |
+| `beforeSend` not firing for native crashes | Expected — `beforeSend` only intercepts Dart-layer events                                              |
+| Silent Flutter errors missed               | Set `options.reportSilentFlutterErrors = true`                                                         |
+| Isolate errors not captured                | Call `isolate.addSentryErrorListener()` on each spawned isolate                                        |
+| Attachments missing from events            | Confirm `SentryWidget(child: MyApp())` is the root widget                                              |
+| ANR false positives on slow devices        | Increase `anrTimeoutInterval` above 5000ms                                                             |
+| Events missing user/tag context            | Set context before error occurs via `Sentry.configureScope()`; native crashes read scope at crash time |
+| Too many events in dashboard               | Lower `sampleRate` (last resort) or use `beforeSend` to drop low-value errors                          |