diff --git a/docs/platforms/dart/common/features/index.mdx b/docs/platforms/dart/common/features/index.mdx index 6a47b7a412cf3..39d5b1ce1f856 100644 --- a/docs/platforms/dart/common/features/index.mdx +++ b/docs/platforms/dart/common/features/index.mdx @@ -12,9 +12,14 @@ Sentry's Dart SDK enables automatic reporting of errors and exceptions, and iden - Dart SDK. - Logging Integration. - Dio Integration. -- Attachments enrich your event by storing additional files, such as config or log files. -- User Feedback provides the ability to collect user information when an event occurs. +- Attachments enrich + your event by storing additional files, such as config or log files. +- User Feedback provides the + ability to collect user information when an event occurs. - Tracing creates transactions for: - HTTP requests. - Dio HTTP library. - File I/O Integration. +- Metrics allow you to send + counters, gauges, and distributions to track application health alongside + errors and traces. diff --git a/docs/platforms/dart/common/metrics/index.mdx b/docs/platforms/dart/common/metrics/index.mdx new file mode 100644 index 0000000000000..88f1d492f0d0a --- /dev/null +++ b/docs/platforms/dart/common/metrics/index.mdx @@ -0,0 +1,30 @@ +--- +title: Set Up Metrics +sidebar_title: Metrics +description: "Metrics allow you to send, view and query counters, gauges and measurements from your Sentry-configured apps to track application health and drill down into related traces, logs, and errors." +sidebar_order: 5756 +beta: true +--- + +With Sentry Metrics, you can send counters, gauges, and distributions from your applications to Sentry. Once in Sentry, these metrics can be viewed alongside relevant errors, and searched using their individual attributes. + + + This feature is currently in open beta. Features in beta are still in progress + and may have bugs. + + +## Requirements + + + +## Usage + + + +## Options + + + +## Default Attributes + + diff --git a/docs/platforms/dart/guides/flutter/features/index.mdx b/docs/platforms/dart/guides/flutter/features/index.mdx index c66011f94b6c2..98628c8009d3a 100644 --- a/docs/platforms/dart/guides/flutter/features/index.mdx +++ b/docs/platforms/dart/guides/flutter/features/index.mdx @@ -9,34 +9,43 @@ Sentry's Flutter SDK enables automatic reporting of errors and exceptions, and i **Features:** - Under the hood the SDK relies on Sentry's Dart SDK: - - You need at least Dart `3.5.0` and Flutter `3.24.0`. - - This SDK includes all the Features of Sentry's Dart SDK. + - You need at least Dart `3.5.0` and Flutter `3.24.0`. + - This SDK includes all the Features of Sentry's Dart SDK. - Automatic native crash error tracking (using both Android and iOS), including: - - Java, Kotlin, C, and C++ code for Android. - - ObjC, Swift, and C for iOS. + - Java, Kotlin, C, and C++ code for Android. + - ObjC, Swift, and C for iOS. - Automatic detection of Application Not Responding (ANR) on Android and App Hangs on iOS. - Offline storage of events. - Events enriched with device data. - Breadcrumbs automatically captured: - - by the Flutter SDK. - - via the Native SDKs Automatic Breadcrumbs for Android and Automatic Breadcrumbs for iOS. - - as well as `http` with the Dart SDK. + - by the Flutter SDK. + - via the Native SDKs Automatic Breadcrumbs for Android and Automatic Breadcrumbs for iOS. + - as well as `http` with the Dart SDK. - Integrations for sqflite, routing and more. For a complete list, see integrations. -- Release Health tracks crash free users and sessions. -- Attachments that can enrich your event by storing additional files, such as config or log files. +- Release Health tracks crash free + users and sessions. +- Attachments that + can enrich your event by storing additional files, such as config or log + files. - Tracing that can track: - - App start time. - - Time to Initial Display and Time to Full Display. - - Slow and Frozen Frames. - - User Interaction which include clicks, long clicks, taps and so on. - - For a complete list see automatic instrumentations. -- User Feedback, providing the ability to collect user feedback when an unexpected event occurs. + - App start time + - Time to Initial Display and Time to Full Display + - Slow and Frozen Frames + - User Interaction which include clicks, long clicks, taps and so on. + - For a complete list see automatic instrumentations. +- User Feedback, providing the + ability to collect user feedback when an unexpected event occurs. - Screenshot and View Hierarchy attachments for errors. -- Profiling collects detailed information about your code at the function level. - - Profiling is currently supported on **iOS** and **macOS**. - - It captures profiles across multiple language layers, including native languages (such as Swift and Objective-C) as well as Dart. +- Profiling collects detailed + information about your code at the function level. + - Profiling is currently supported on **iOS** and **macOS**. + - It captures profiles across multiple language layers, including native languages (such as Swift and Objective-C) as well as Dart. - Source Context shows snippets of code around the location of stack frames. -- Sentry Dart Plugin makes uploading debug symbols easy and automatic. +- Sentry Dart Plugin makes + uploading debug symbols easy and automatic. +- Metrics allow you to send counters, + gauges, and distributions to track application health alongside errors and + traces. **Web Limitations:** @@ -55,4 +64,3 @@ Sentry supports Flutter on Linux and Windows as well, with the following limitat - [Release Health](/product/releases/health/) isn't supported. When running on macOS, you can expect the same feature set as on iOS. - diff --git a/platform-includes/metrics/default-attributes/dart.flutter.mdx b/platform-includes/metrics/default-attributes/dart.flutter.mdx new file mode 100644 index 0000000000000..cf98e2a5f88fa --- /dev/null +++ b/platform-includes/metrics/default-attributes/dart.flutter.mdx @@ -0,0 +1,15 @@ +Sentry automatically attaches these attributes to every metric: + +| Attribute | Description | Context | +|-----------|-------------|---------| +| `sentry.environment` | Environment from SDK config | Always | +| `sentry.release` | Release version from SDK config | Always | +| `sentry.sdk.name` | SDK name | Always | +| `sentry.sdk.version` | SDK version | Always | +| `os.name` | Operating system name | If available | +| `os.version` | Operating system version | If available | +| `device.brand` | Device manufacturer | If available | +| `device.model` | Device model name | If available | +| `device.family` | Device family | If available | +| `user.id`, `user.name`, `user.email` | User identifiers | If `sendDefaultPii` enabled | +| `sentry.replay_id` | Session replay ID | If replay available | diff --git a/platform-includes/metrics/default-attributes/dart.mdx b/platform-includes/metrics/default-attributes/dart.mdx new file mode 100644 index 0000000000000..191a4ad5c7320 --- /dev/null +++ b/platform-includes/metrics/default-attributes/dart.mdx @@ -0,0 +1,12 @@ +Sentry automatically attaches these attributes to every metric: + +| Attribute | Description | Context | +|-----------|-------------|---------| +| `sentry.environment` | Environment from SDK config | Always | +| `sentry.release` | Release version from SDK config | Always | +| `sentry.sdk.name` | SDK name | Always | +| `sentry.sdk.version` | SDK version | Always | +| `os.name` | Operating system name | If available | +| `os.version` | Operating system version | If available | +| `user.id`, `user.name`, `user.email` | User identifiers | If `sendDefaultPii` enabled | +| `sentry.replay_id` | Session replay ID | If replay available | diff --git a/platform-includes/metrics/options/dart.flutter.mdx b/platform-includes/metrics/options/dart.flutter.mdx new file mode 100644 index 0000000000000..bbd4f3d74f3d3 --- /dev/null +++ b/platform-includes/metrics/options/dart.flutter.mdx @@ -0,0 +1,53 @@ + + + + +### beforeSendMetric + +Filter or modify metrics before sending. Return `null` to drop a metric. + + + + +```dart +import 'package:sentry_flutter/sentry_flutter.dart'; + +await SentryFlutter.init((options) { + options.dsn = '___PUBLIC_DSN___'; + options.beforeSendMetric = (metric) { + // Drop specific metrics + if (metric.attributes.containsKey('debug')) { + return null; + } + + // Return the metric to send it + return metric; + }; +}); +``` + + + + + + + +### Disable Metrics + +Set `enableMetrics: false` to disable metrics collection entirely. + + + + +```dart +import 'package:sentry_flutter/sentry_flutter.dart'; + +await SentryFlutter.init((options) { + options.dsn = '___PUBLIC_DSN___'; + options.enableMetrics = false; +}); +``` + + + + diff --git a/platform-includes/metrics/options/dart.mdx b/platform-includes/metrics/options/dart.mdx new file mode 100644 index 0000000000000..b7c0fc93c994a --- /dev/null +++ b/platform-includes/metrics/options/dart.mdx @@ -0,0 +1,54 @@ + + + + +### beforeSendMetric + +Filter or modify metrics before sending. Return `null` to drop a metric. + + + + +```dart +import 'package:sentry/sentry.dart'; + +await Sentry.init((options) { + options.dsn = '___PUBLIC_DSN___'; + options.beforeSendMetric = (metric) { + // Drop specific metrics + if (metric.attributes.containsKey('debug')) { + return null; + } + + // Return the metric to send it + return metric; + }; +}); +``` + + + + + + + +### Disable Metrics + +Set `enableMetrics: false` to disable metrics collection entirely. + + + + +```dart +import 'package:sentry/sentry.dart'; + +// Disable metrics +await Sentry.init((options) { + options.dsn = '___PUBLIC_DSN___'; + options.enableMetrics = false; +}); +``` + + + + diff --git a/platform-includes/metrics/requirements/dart.flutter.mdx b/platform-includes/metrics/requirements/dart.flutter.mdx new file mode 100644 index 0000000000000..4d0a0c523a2d0 --- /dev/null +++ b/platform-includes/metrics/requirements/dart.flutter.mdx @@ -0,0 +1 @@ +Metrics are supported in Sentry Flutter SDK version `9.11.0` and above. diff --git a/platform-includes/metrics/requirements/dart.mdx b/platform-includes/metrics/requirements/dart.mdx new file mode 100644 index 0000000000000..caa6f2e75ef00 --- /dev/null +++ b/platform-includes/metrics/requirements/dart.mdx @@ -0,0 +1 @@ +Metrics are supported in Sentry Dart SDK version `9.11.0` and above. diff --git a/platform-includes/metrics/usage/dart.flutter.mdx b/platform-includes/metrics/usage/dart.flutter.mdx new file mode 100644 index 0000000000000..aba8588140dff --- /dev/null +++ b/platform-includes/metrics/usage/dart.flutter.mdx @@ -0,0 +1,128 @@ + + + + +### Metric Types + +| Type | Use For | +|------|---------| +| `count` | Events (orders, clicks, API calls) | +| `gauge` | Current values (queue depth, connections) | +| `distribution` | Value ranges (response times, payload sizes) | + +No setup required beyond SDK initialization. + + + + +```dart +import 'package:sentry_flutter/sentry_flutter.dart'; + +// Count occurrences +Sentry.metrics.count('orders_created', 1); + +// Track current values +Sentry.metrics.gauge('active_connections', 42); + +// Track distributions +Sentry.metrics.distribution( + 'api_latency', + 187, + unit: 'millisecond', +); +``` + + + + + +### Attributes + + + + + +#### Filtering and Grouping + +Attributes let you filter and group metrics in Sentry. Use them for: +- Environment segmentation +- Feature flag tracking +- User tier analysis + +Each metric has a **2KB size limit**. If you exceed this, the metric will be dropped. + + + + +```dart +Sentry.metrics.count( + 'api_calls', + 1, + attributes: { + 'endpoint': SentryAttribute.string('/api/orders'), + 'user_tier': SentryAttribute.string('pro'), + 'region': SentryAttribute.string('us-west'), + }, +); +``` + + + + + + + +#### Scope Attributes + +Use scope APIs to set attributes that apply to all metrics while the scope is active. + + + + +```dart +// Add attributes to the global scope +Sentry.setAttributes({'is_admin': SentryAttribute.bool(true)}); + +// All scope attributes are added to metrics +Sentry.metrics.count('clicks', 1); +Sentry.metrics.gauge( + 'time_since_refresh', + 4, + unit: 'second', +); +``` + + + + + + + +#### Units + +For `gauge` and `distribution` metrics, specify a unit to help Sentry display values in a human-readable format. + +Common units: `millisecond`, `second`, `byte`, `kilobyte`, `megabyte`. +Use `SentryMetricUnit` to conveniently access supported units in Dart. +See [supported units](https://develop.sentry.dev/sdk/telemetry/attributes/#units) for the full list. + + + + +```dart +Sentry.metrics.distribution( + 'response_time', + 187.5, + unit: SentryMetricUnit.millisecond, +); + +Sentry.metrics.gauge( + 'memory_usage', + 1024, + unit: SentryMetricUnit.byte, +); +``` + + + + diff --git a/platform-includes/metrics/usage/dart.mdx b/platform-includes/metrics/usage/dart.mdx new file mode 100644 index 0000000000000..cc860333f71e5 --- /dev/null +++ b/platform-includes/metrics/usage/dart.mdx @@ -0,0 +1,128 @@ + + + + +### Metric Types + +| Type | Use For | +|------|---------| +| `count` | Events (orders, clicks, API calls) | +| `gauge` | Current values (queue depth, connections) | +| `distribution` | Value ranges (response times, payload sizes) | + +No setup required beyond SDK initialization. + + + + +```dart +import 'package:sentry/sentry.dart'; + +// Count occurrences +Sentry.metrics.count('orders_created', 1); + +// Track current values +Sentry.metrics.gauge('active_connections', 42); + +// Track distributions +Sentry.metrics.distribution( + 'api_latency', + 187, + unit: 'millisecond', +); +``` + + + + + +### Attributes + + + + + +#### Filtering and Grouping + +Attributes let you filter and group metrics in Sentry. Use them for: +- Environment segmentation +- Feature flag tracking +- User tier analysis + +Each metric has a **2KB size limit**. If you exceed this, the metric will be dropped. + + + + +```dart +Sentry.metrics.count( + 'api_calls', + 1, + attributes: { + 'endpoint': SentryAttribute.string('/api/orders'), + 'user_tier': SentryAttribute.string('pro'), + 'region': SentryAttribute.string('us-west'), + }, +); +``` + + + + + + + +#### Scope Attributes + +Use scope APIs to set attributes that apply to all metrics while the scope is active. + + + + +```dart +// Add attributes to the global scope +Sentry.setAttributes({'is_admin': SentryAttribute.bool(true)}); + +// All scope attributes are added to metrics +Sentry.metrics.count('clicks', 1); +Sentry.metrics.gauge( + 'time_since_refresh', + 4, + unit: 'second', +); +``` + + + + + + + +#### Units + +For `gauge` and `distribution` metrics, specify a unit to help Sentry display values in a human-readable format. + +Common units: `millisecond`, `second`, `byte`, `kilobyte`, `megabyte`. +Use `SentryMetricUnit` to conveniently access supported units in Dart. +See [supported units](https://develop.sentry.dev/sdk/telemetry/attributes/#units) for the full list. + + + + +```dart +Sentry.metrics.distribution( + 'response_time', + 187.5, + unit: SentryMetricUnit.millisecond, +); + +Sentry.metrics.gauge( + 'memory_usage', + 1024, + unit: SentryMetricUnit.byte, +); +``` + + + +