@danieljvdm/dev-kit 1.0.2 → 2.0.0

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

@@ -0,0 +1,387 @@
+# Logging — Sentry Flutter SDK
+
+> **Minimum SDK:** `sentry_flutter` ≥ **9.5.0** for structured logs (`enableLogs`)\
+> **`sentry_logging` integration:** `sentry_logging` ≥ **9.5.0** + Dart `logging`
+> package ≥ **1.0.0**\
+> **`enableLogs` flag:** off by default — must be explicitly enabled
+
+Flutter/Dart has two complementary logging paths:
+
+1. **Sentry structured logs** — `Sentry.logger.*` API (direct) or via `sentry_logging`
+   integration (bridges the Dart `logging` package)
+2. **Breadcrumbs** — Automatic breadcrumbs from `sentry_logging` for navigation and
+   debug events
+
+---
+
+## Table of Contents
+
+1. [Enabling Logs](#1-enabling-logs)
+2. [Direct Logger API](#2-direct-logger-api)
+3. [sentry_logging Integration (Dart logging package)](#3-sentry_logging-integration-dart-logging-package)
+4. [Structured Attributes](#4-structured-attributes)
+5. [Filtering with beforeSendLog](#5-filtering-with-beforesendlog)
+6. [Log Correlation with Traces](#6-log-correlation-with-traces)
+7. [Configuration Reference](#7-configuration-reference)
+8. [Known Limitations](#8-known-limitations)
+9. [Troubleshooting](#9-troubleshooting)
+
+---
+
+## 1. Enabling Logs
+
+`enableLogs` is **off by default** — opt in explicitly:
+
+```dart
+import 'package:sentry_flutter/sentry_flutter.dart';
+
+Future<void> main() async {
+  await SentryFlutter.init(
+    (options) {
+      options.dsn = 'YOUR_DSN';
+      options.enableLogs = true; // required — logs are disabled unless this is set
+    },
+    appRunner: () => runApp(MyApp()),
+  );
+}
+```
+
+---
+
+## 2. Direct Logger API
+
+Use `Sentry.logger` to emit structured logs at six severity levels:
+
+```dart
+import 'package:sentry/sentry.dart';
+
+// Fine-grained debugging — high volume, filter in production
+Sentry.logger.trace('Starting checkout flow', attributes: {'step': SentryAttribute.string('init')});
+
+// Development diagnostics
+Sentry.logger.debug('Cache lookup', attributes: {
+  'key': SentryAttribute.string('user:123'),
+  'hit': SentryAttribute.bool(false),
+});
+
+// Normal operations and business milestones
+Sentry.logger.info('Order created', attributes: {
+  'orderId': SentryAttribute.string('order_456'),
+  'total': SentryAttribute.double(99.99),
+});
+
+// Degraded state, approaching limits
+Sentry.logger.warn('Rate limit approaching', attributes: {
+  'endpoint': SentryAttribute.string('/api/search/'),
+  'current': SentryAttribute.int(95),
+  'max': SentryAttribute.int(100),
+});
+
+// Failures requiring attention
+Sentry.logger.error('Payment failed', attributes: {
+  'reason': SentryAttribute.string('card_declined'),
+  'userId': SentryAttribute.string('u_1'),
+});
+
+// Critical failures — app or subsystem is down
+Sentry.logger.fatal('Database unavailable', attributes: {'host': SentryAttribute.string('db-primary')});
+```
+
+### Level selection guide
+
+| Level   | When to use                                                      |
+| ------- | ---------------------------------------------------------------- |
+| `trace` | Step-by-step internals, loop iterations, low-level flow tracking |
+| `debug` | Diagnostic info useful during development                        |
+| `info`  | Business events, user actions, meaningful state transitions      |
+| `warn`  | Recoverable errors, degraded performance, approaching limits     |
+| `error` | Failures that need investigation but don’t crash the app         |
+| `fatal` | Unrecoverable failures — app or critical subsystem is down       |
+
+**Attribute value types:** `String`, `int`, `double`, and `bool` only.
+Other types will be dropped or coerced.
+
+---
+
+## 3. sentry_logging Integration (Dart logging package)
+
+The `sentry_logging` package bridges the standard Dart `logging` package to Sentry.
+This is ideal for projects already using `logging` for structured output.
+
+### Installation
+
+```yaml
+# pubspec.yaml
+dependencies:
+  sentry_flutter: ^9.14.0
+  sentry_logging: ^9.14.0
+  logging: ^1.0.0
+```
+
+### Configuration
+
+```dart
+import 'package:sentry_flutter/sentry_flutter.dart';
+import 'package:sentry_logging/sentry_logging.dart';
+import 'package:logging/logging.dart';
+
+Future<void> main() async {
+  await SentryFlutter.init(
+    (options) {
+      options.dsn = 'YOUR_DSN';
+      options.enableLogs = true;
+
+      options.addIntegration(
+        LoggingIntegration(
+          // Minimum level that creates breadcrumbs (default: Level.INFO)
+          minBreadcrumbLevel: Level.INFO,
+          // Minimum level that creates Sentry error events (default: Level.SEVERE)
+          minEventLevel: Level.SEVERE,
+          // Minimum level that creates structured logs (default: Level.INFO)
+          minSentryLogLevel: Level.INFO,
+        ),
+      );
+    },
+    appRunner: () => runApp(MyApp()),
+  );
+}
+```
+
+### Usage with the logging package
+
+```dart
+import 'package:logging/logging.dart';
+
+final _logger = Logger('PaymentService');
+
+class PaymentService {
+  Future<void> processPayment(String orderId, double amount) async {
+    _logger.info('Processing payment for order $orderId (amount: $amount)');
+
+    try {
+      final result = await _chargeCard(amount);
+      _logger.info(
+          'Payment succeeded for order $orderId (transaction: ${result.transactionId})');
+    } catch (e, stackTrace) {
+      // Pass error and stackTrace for accurate reporting
+      _logger.severe('Payment failed', e, stackTrace);
+    }
+  }
+}
+```
+
+### Stack trace handling
+
+The Dart `logging` package does **not** automatically capture stack traces.
+Configure it explicitly:
+
+```dart
+// Option 1 — automatic stack trace capture at SEVERE and above
+Logger.root.recordStackTraceAtLevel = Level.SEVERE;
+
+// Option 2 — pass stack trace manually to each log call
+Logger('MyService').severe('Error occurred', error, stackTrace);
+```
+
+### What each log level produces
+
+| Dart Level                    | ≥ `minBreadcrumbLevel`     | ≥ `minSentryLogLevel` | ≥ `minEventLevel` |
+| ----------------------------- | -------------------------- | --------------------- | ----------------- |
+| `Level.FINEST`/`FINER`/`FINE` | Breadcrumb (if configured) | Structured log        | —                 |
+| `Level.INFO`/`CONFIG`         | ✅ Breadcrumb              | ✅ Structured log     | —                 |
+| `Level.WARNING`               | ✅ Breadcrumb              | ✅ Structured log     | —                 |
+| `Level.SEVERE`                | ✅ Breadcrumb              | ✅ Structured log     | ✅ Error event    |
+| `Level.SHOUT`                 | ✅ Breadcrumb              | ✅ Structured log     | ✅ Error event    |
+
+---
+
+## 4. Structured Attributes
+
+Attributes passed to `Sentry.logger.*` become **queryable columns** in the Sentry Logs
+UI:
+
+```dart
+Sentry.logger.info('Checkout completed', attributes: {
+  'orderId': SentryAttribute.string(order.id),
+  'userId': SentryAttribute.string(user.id),
+  'cartValue': SentryAttribute.double(cart.total),
+  'itemCount': SentryAttribute.int(cart.items.length),
+  'paymentMethod': SentryAttribute.string('stripe'),
+  'durationMs': SentryAttribute.int(
+      DateTime.now().difference(startTime).inMilliseconds),
+});
+
+Sentry.logger.error('Navigation failed', attributes: {
+  'fromRoute': SentryAttribute.string('/home'),
+  'toRoute': SentryAttribute.string('/profile'),
+  'errorCode': SentryAttribute.string(err.code),
+  'retryable': SentryAttribute.bool(true),
+});
+```
+
+### Scope-level attributes
+
+Set attributes on the scope and they are automatically attached to all logs emitted
+while the scope is active:
+
+```dart
+// Global scope — set once at app startup
+Sentry.configureScope((scope) {
+  scope.setContexts('app', {
+    'version': '2.1.0',
+    'build': '42',
+    'flavor': 'production',
+  });
+});
+
+// Per-operation scope — configure the current scope before logging
+Sentry.configureScope((scope) {
+  scope.setTag('orderId', 'ord_789');
+  scope.setTag('paymentMethod', 'stripe');
+});
+
+Sentry.logger.info('Validating cart', attributes: {'cartId': SentryAttribute.string(cart.id)});
+await processPayment();
+Sentry.logger.info('Payment complete');
+// Both logs above carry orderId and paymentMethod tags
+```
+
+### Auto-attached attributes
+
+The SDK automatically attaches these to every log:
+
+| Attribute                                | Source                                       |
+| ---------------------------------------- | -------------------------------------------- |
+| `sentry.environment`                     | `options.environment`                        |
+| `sentry.release`                         | `options.release`                            |
+| `sentry.sdk.name` / `sentry.sdk.version` | SDK internals                                |
+| `user.id`, `user.email`                  | `Sentry.setUser()` when set                  |
+| `origin`                                 | Identifies which integration emitted the log |
+
+---
+
+## 5. Filtering with beforeSendLog
+
+Filter or mutate every log before it is transmitted.
+Return `null` to drop the log entirely:
+
+```dart
+await SentryFlutter.init(
+  (options) {
+    options.dsn = 'YOUR_DSN';
+    options.enableLogs = true;
+
+    options.beforeSendLog = (log) {
+      // Drop trace/debug in production to reduce volume
+      if (log.level == SentryLogLevel.trace ||
+          log.level == SentryLogLevel.debug) {
+        return null;
+      }
+
+      // Scrub sensitive attribute values
+      if (log.attributes.containsKey('password')) {
+        log.attributes.remove('password');
+      }
+      if (log.attributes.containsKey('creditCard')) {
+        log.attributes['creditCard'] = '[REDACTED]';
+      }
+
+      return log;
+    };
+  },
+  appRunner: () => runApp(MyApp()),
+);
+```
+
+---
+
+## 6. Log Correlation with Traces
+
+When tracing is enabled, logs emitted inside an active span are **automatically
+correlated** in the Sentry UI. You can navigate from a log to its parent transaction.
+
+```dart
+import 'package:sentry/sentry.dart';
+
+Future<void> processOrder(String orderId) async {
+  final transaction = Sentry.startTransaction('process-order', 'task');
+  try {
+    Sentry.logger.info('Validating cart', attributes: {'orderId': SentryAttribute.string(orderId)});
+    await validateCart(orderId);
+
+    Sentry.logger.info('Charging payment', attributes: {'orderId': SentryAttribute.string(orderId)});
+    await chargePayment(orderId);
+
+    Sentry.logger.info('Confirming order', attributes: {'orderId': SentryAttribute.string(orderId)});
+    await confirmOrder(orderId);
+
+    transaction.finish(status: const SpanStatus.ok());
+  } catch (e) {
+    transaction.finish(status: const SpanStatus.internalError());
+    rethrow;
+  }
+  // All three logs are linked to the process-order span in the trace view
+}
+```
+
+Enable tracing in `SentryFlutter.init`:
+
+```dart
+options.tracesSampleRate = 1.0; // required for log-to-trace correlation
+options.enableLogs = true;
+```
+
+---
+
+## 7. Configuration Reference
+
+### `SentryFlutter.init` options
+
+| Option          | Type                             | Default | Description                                                    |
+| --------------- | -------------------------------- | ------- | -------------------------------------------------------------- |
+| `enableLogs`    | `bool`                           | `false` | Master switch — must be `true` for all structured logging      |
+| `beforeSendLog` | `SentryLog? Function(SentryLog)` | `null`  | Filter/mutate logs before transmission. Return `null` to drop. |
+
+### `LoggingIntegration` options
+
+| Option               | Type    | Default        | Description                                             |
+| -------------------- | ------- | -------------- | ------------------------------------------------------- |
+| `minBreadcrumbLevel` | `Level` | `Level.INFO`   | Minimum Dart log level to create Sentry breadcrumbs     |
+| `minEventLevel`      | `Level` | `Level.SEVERE` | Minimum Dart log level to create Sentry error events    |
+| `minSentryLogLevel`  | `Level` | `Level.INFO`   | Minimum Dart log level to create Sentry structured logs |
+
+### Version requirements
+
+| Feature                        | Min Package      | Min SDK Version |
+| ------------------------------ | ---------------- | --------------- |
+| `enableLogs` / structured logs | `sentry_flutter` | `9.5.0`         |
+| `sentry_logging` integration   | `sentry_logging` | `9.5.0`         |
+| `beforeSendLog` hook           | `sentry_flutter` | `9.5.0`         |
+
+---
+
+## 8. Known Limitations
+
+| Limitation                           | Details                                                                                     |
+| ------------------------------------ | ------------------------------------------------------------------------------------------- |
+| Crash buffer loss                    | Logs buffered since last flush are lost on unexpected termination before the buffer is sent |
+| No per-log sampling                  | Use `beforeSendLog` to reduce volume — sampling is all-or-nothing                           |
+| Dart logging package stack traces    | Must be enabled manually via `Logger.root.recordStackTraceAtLevel` or passed explicitly     |
+| `sentry_logging` is separate package | Must be added to `pubspec.yaml` separately — not bundled with `sentry_flutter`              |
+| `enableLogs` is off by default       | Logs are silently discarded if `enableLogs` is not `true`                                   |
+
+---
+
+## 9. Troubleshooting
+
+| Issue                                                  | Solution                                                                                                         |
+| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| Logs not appearing in Sentry                           | Verify `enableLogs: true` is set in `SentryFlutter.init()`                                                       |
+| `Sentry.logger` not available                          | Import `package:sentry/sentry.dart`; check `sentry_flutter` ≥ 9.5.0                                              |
+| `LoggingIntegration` type not found                    | Add `sentry_logging` to `pubspec.yaml` and import `package:sentry_logging/sentry_logging.dart`                   |
+| Logs appear but no stack traces on errors              | Set `Logger.root.recordStackTraceAtLevel = Level.SEVERE` or pass `stackTrace` manually                           |
+| Attribute values showing `[Filtered]`                  | Server-side PII scrubbing rule matched — adjust **Data Scrubbing** settings in your Sentry project               |
+| Logs not linked to traces                              | Enable tracing (`tracesSampleRate > 0`) and emit logs inside an active transaction (`Sentry.startTransaction()`) |
+| Too many logs in production                            | Use `beforeSendLog` to drop `trace`/`debug` levels                                                               |
+| `sentry_logging` logs not forwarded as structured logs | Check that `minSentryLogLevel` is set to the expected level and `enableLogs: true`                               |
+| Logs disappearing silently                             | Check your Sentry org stats for rate limiting; verify log payload < 1 MB                                         |

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

@@ -0,0 +1,310 @@
+# Metrics — Sentry Flutter SDK
+
+> **Minimum SDK:** `sentry_flutter` ≥ **9.11.0** for trace-connected metrics\
+> **Supported metric types:** Counter, Distribution, Gauge (no `set` type)\
+> **Per-metric key limit:** 2 KB
+
+Metrics let you track quantitative data about your app’s behavior — things like button
+tap counts, API latency distributions, or active session gauges.
+Unlike error events, metrics are aggregated before being sent to Sentry.
+
+---
+
+## Table of Contents
+
+1. [Metric Types Overview](#1-metric-types-overview)
+2. [Counter](#2-counter)
+3. [Distribution](#3-distribution)
+4. [Gauge](#4-gauge)
+5. [Tags and Trace Correlation](#5-tags-and-trace-correlation)
+6. [Configuration Reference](#6-configuration-reference)
+7. [Known Limitations](#7-known-limitations)
+8. [Troubleshooting](#8-troubleshooting)
+
+---
+
+## 1. Metric Types Overview
+
+| Type             | Method                          | Use Case                     | Example                          |
+| ---------------- | ------------------------------- | ---------------------------- | -------------------------------- |
+| **Counter**      | `Sentry.metrics.increment()`    | Count occurrences            | Button taps, API calls, errors   |
+| **Distribution** | `Sentry.metrics.distribution()` | Measure value distributions  | API response times, image sizes  |
+| **Gauge**        | `Sentry.metrics.gauge()`        | Track min/max/avg of a value | Active sessions, queue depth     |
+| ~~Set~~          | ~~`Sentry.metrics.set()`~~      | ~~Count unique occurrences~~ | **Not supported in Flutter SDK** |
+
+> **Note on `set` metrics:** The `set` type is not available in the Sentry Flutter/Dart
+> SDK. Use a counter or external unique-value tracking if you need to count distinct
+> users or IDs.
+
+---
+
+## 2. Counter
+
+Counters track how many times something happens.
+Use `increment()` — each call adds to the running total.
+
+```dart
+import 'package:sentry/sentry.dart';
+
+// Simple increment (adds 1)
+Sentry.metrics.increment('button.tapped');
+
+// Custom increment value
+Sentry.metrics.increment('orders.processed', value: 5.0);
+
+// With tags for segmentation
+Sentry.metrics.increment(
+  'api.request',
+  value: 1.0,
+  unit: SentryMeasurementUnit.none,
+  tags: {
+    'endpoint': '/api/search',
+    'method': 'GET',
+    'status': '200',
+  },
+);
+```
+
+### Practical examples
+
+```dart
+// Track feature usage
+void onShareButtonTapped() {
+  Sentry.metrics.increment('feature.share.tapped');
+  // existing share logic...
+}
+
+// Count errors by type
+void onPaymentError(String errorType) {
+  Sentry.metrics.increment(
+    'payment.error',
+    tags: {'type': errorType},
+  );
+}
+
+// Track A/B test variant interactions
+void onExperimentAction(String variant, String action) {
+  Sentry.metrics.increment(
+    'experiment.action',
+    tags: {
+      'variant': variant,
+      'action': action,
+    },
+  );
+}
+```
+
+---
+
+## 3. Distribution
+
+Distributions capture the **spread of values** over time — min, max, sum, count, and
+percentiles (p50, p75, p95, p99). Ideal for latency and size measurements.
+
+```dart
+import 'package:sentry/sentry.dart';
+
+// API response time in milliseconds
+final stopwatch = Stopwatch()..start();
+await fetchUserData(userId);
+stopwatch.stop();
+
+Sentry.metrics.distribution(
+  'api.response_time',
+  value: stopwatch.elapsedMilliseconds.toDouble(),
+  unit: SentryMeasurementUnit.duration(DurationSentryMeasurementUnit.milliSecond),
+  tags: {'endpoint': '/users', 'cached': 'false'},
+);
+```
+
+### Unit types
+
+```dart
+// Duration
+SentryMeasurementUnit.duration(DurationSentryMeasurementUnit.nanoSecond)
+SentryMeasurementUnit.duration(DurationSentryMeasurementUnit.microSecond)
+SentryMeasurementUnit.duration(DurationSentryMeasurementUnit.milliSecond)
+SentryMeasurementUnit.duration(DurationSentryMeasurementUnit.second)
+SentryMeasurementUnit.duration(DurationSentryMeasurementUnit.minute)
+SentryMeasurementUnit.duration(DurationSentryMeasurementUnit.hour)
+
+// Data sizes
+SentryMeasurementUnit.information(InformationSentryMeasurementUnit.byte)
+SentryMeasurementUnit.information(InformationSentryMeasurementUnit.kilobyte)
+SentryMeasurementUnit.information(InformationSentryMeasurementUnit.megabyte)
+SentryMeasurementUnit.information(InformationSentryMeasurementUnit.gigabyte)
+
+// Fractions
+SentryMeasurementUnit.fraction(FractionSentryMeasurementUnit.ratio)
+SentryMeasurementUnit.fraction(FractionSentryMeasurementUnit.percent)
+
+// Custom / unitless
+SentryMeasurementUnit.none
+SentryMeasurementUnit.custom('items')
+```
+
+### Practical examples
+
+```dart
+// Image load time
+Future<void> loadImage(String url) async {
+  final start = DateTime.now();
+  await precacheImage(NetworkImage(url), context);
+  final elapsed = DateTime.now().difference(start);
+
+  Sentry.metrics.distribution(
+    'image.load_time',
+    value: elapsed.inMilliseconds.toDouble(),
+    unit: SentryMeasurementUnit.duration(DurationSentryMeasurementUnit.milliSecond),
+    tags: {'cached': 'false'},
+  );
+}
+
+// Payload size tracking
+void onApiResponse(http.Response response) {
+  Sentry.metrics.distribution(
+    'api.response_size',
+    value: response.contentLength?.toDouble() ?? 0,
+    unit: SentryMeasurementUnit.information(InformationSentryMeasurementUnit.byte),
+    tags: {'endpoint': response.request?.url.path ?? 'unknown'},
+  );
+}
+
+// Cart value distribution
+void onCheckoutCompleted(double cartTotal) {
+  Sentry.metrics.distribution(
+    'checkout.cart_value',
+    value: cartTotal,
+    unit: SentryMeasurementUnit.none,
+  );
+}
+```
+
+---
+
+## 4. Gauge
+
+Gauges track the **statistical properties** (last, min, max, sum, count) of a set of
+values emitted during the aggregation window.
+Use for things that have a meaningful current state.
+
+```dart
+import 'package:sentry/sentry.dart';
+
+// Track active background operations
+Sentry.metrics.gauge(
+  'background.tasks.active',
+  value: activeTaskCount.toDouble(),
+);
+
+// Track session depth
+Sentry.metrics.gauge(
+  'navigation.stack_depth',
+  value: Navigator.of(context).canPop() ? stackDepth.toDouble() : 0,
+);
+
+// Monitor cache entries
+Sentry.metrics.gauge(
+  'cache.entry_count',
+  value: imageCache.currentSize.toDouble(),
+  tags: {'type': 'image_cache'},
+);
+```
+
+---
+
+## 5. Tags and Trace Correlation
+
+### Tags
+
+All metric types accept a `tags` map.
+Tags are key-value strings used to **filter and group metrics** in the Sentry Metrics
+UI:
+
+```dart
+Sentry.metrics.increment(
+  'checkout.step',
+  tags: {
+    'step': 'payment',        // string values only
+    'platform': 'ios',
+    'user_type': 'subscriber',
+  },
+);
+```
+
+### Trace correlation
+
+As of `sentry_flutter` 9.11.0, metrics are **automatically linked to the active trace**
+when emitted inside a span.
+This allows you to view metric data alongside transaction performance in the Sentry UI:
+
+```dart
+final transaction = Sentry.startTransaction('checkout', 'ui.action');
+try {
+  // This increment is linked to the checkout transaction
+  Sentry.metrics.increment('checkout.started');
+
+  final start = DateTime.now();
+  await processCheckout();
+  final elapsed = DateTime.now().difference(start);
+
+  Sentry.metrics.distribution(
+    'checkout.duration',
+    value: elapsed.inMilliseconds.toDouble(),
+    unit: SentryMeasurementUnit.duration(DurationSentryMeasurementUnit.milliSecond),
+  );
+
+  Sentry.metrics.increment('checkout.completed');
+
+  transaction.finish(status: const SpanStatus.ok());
+} catch (e) {
+  transaction.finish(status: const SpanStatus.internalError());
+  rethrow;
+}
+```
+
+---
+
+## 6. Configuration Reference
+
+No special configuration is required for metrics beyond initializing the SDK with a
+valid DSN. Metrics are enabled by default.
+
+| Method                                                  | Signature                   |
+| ------------------------------------------------------- | --------------------------- |
+| `Sentry.metrics.increment(key, {value, unit, tags})`    | Increment a counter         |
+| `Sentry.metrics.distribution(key, {value, unit, tags})` | Record a distribution value |
+| `Sentry.metrics.gauge(key, {value, unit, tags})`        | Record a gauge observation  |
+
+### Version requirements
+
+| Feature                      | Min SDK  |
+| ---------------------------- | -------- |
+| `Sentry.metrics.*` basic API | `9.0.0`  |
+| Trace-connected metrics      | `9.11.0` |
+
+---
+
+## 7. Known Limitations
+
+| Limitation                 | Details                                                                                                                                                           |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| No `set` type              | `Sentry.metrics.set()` is **not supported** in the Flutter/Dart SDK. Use counters or external tracking for unique-value counting.                                 |
+| 2 KB per-metric key limit  | The metric key name + all tag key-value pairs must fit within 2 KB total.                                                                                         |
+| Active development         | The metrics API is stable but under active development. Some edge cases may change in future minor versions.                                                      |
+| Aggregation window         | Metrics are aggregated locally before being flushed. Individual data points are not preserved — you see aggregations (sum, count, min, max).                      |
+| No sampling for metrics    | Unlike errors and transactions, there is no sample rate for metrics — all emitted metrics are sent. Use tags and filtering instead of emitting fewer data points. |
+| Tag values must be strings | Passing non-string tag values will be coerced or dropped.                                                                                                         |
+
+---
+
+## 8. Troubleshooting
+
+| Issue                                     | Solution                                                                                                                         |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Metrics not appearing in Sentry           | Verify DSN is correct and the SDK is initialized. Check Sentry → Metrics to ensure the feature is enabled for your organization. |
+| SDK version doesn’t have `Sentry.metrics` | Upgrade `sentry_flutter` to ≥ 9.0.0                                                                                              |
+| Metrics not linked to traces              | Upgrade to `sentry_flutter` ≥ 9.11.0 and emit metrics inside an active transaction (`Sentry.startTransaction()`)                 |
+| `set` metric type not available           | Expected — not supported in Flutter SDK. Use `increment` with a counter instead.                                                 |
+| Metrics appear intermittently             | Expected — metrics are batched and flushed on a schedule. Low-volume metrics may appear in Sentry with a delay.                  |
+| Tags not showing up correctly             | Verify all tag values are strings; check total metric key + tags size is under 2 KB                                              |