diff --git a/docs/platforms/dart/common/index.mdx b/docs/platforms/dart/common/index.mdx index a15ba542b8fb8e..f07037199fb884 100644 --- a/docs/platforms/dart/common/index.mdx +++ b/docs/platforms/dart/common/index.mdx @@ -1,6 +1,6 @@ --- title: Dart -description: Learn how to set up Sentry in your Dart app, capture your first errors and traces, and view them in Sentry. +description: Learn how to set up Sentry in your Dart app, capture your first events, and view them in Sentry. caseStyle: camelCase supportLevel: production sdk: sentry.dart @@ -33,9 +33,8 @@ dependencies: ## Configure -Choose the features you want to configure, and this guide will show you how: - - +Initialize **Error Monitoring** with `Sentry.init()` and run your application in its `appRunner` callback to capture uncaught exceptions and unhandled asynchronous errors. **Logs** and **Application Metrics** are enabled by default in SDK v10, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing**. @@ -43,40 +42,83 @@ Choose the features you want to configure, and this guide will show you how: Configuration should happen as **early as possible** in your application's lifecycle. -Import and initialize the SDK in your app's entry point: +Import and initialize the SDK in your app's entry point as shown in the code snippet below. + +The snippet also turns on: + +- Tracing: via `tracesSampleRate` +- Additional user and request data: via `sendDefaultPii` + +To skip tracing, omit `tracesSampleRate`. To discard logs or metrics, return `null` from `beforeSendLog` or `beforeSendMetric`. ```dart import 'package:sentry/sentry.dart'; Future main() async { - await Sentry.init((options) { - options.dsn = '___PUBLIC_DSN___'; - // Adds request headers and IP for users, for more info visit: - // https://docs.sentry.io/platforms/dart/data-management/data-collected/ - options.sendDefaultPii = true; - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% of transactions for tracing. - // We recommend adjusting this value in production. - options.tracesSampleRate = 1.0; - // ___PRODUCT_OPTION_END___ performance - }); - - // you can also configure SENTRY_DSN, SENTRY_RELEASE, SENTRY_DIST, and - // SENTRY_ENVIRONMENT via Dart environment variable (--dart-define) + await Sentry.init( + (options) { + options.dsn = '___PUBLIC_DSN___'; + + // Allows sending default personal data, such as IP addresses, + // when available from the SDK's integrations. + options.sendDefaultPii = true; + + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. + options.tracesSampleRate = 1.0; + }, + appRunner: () async { + // Start your application here. + }, + ); + + // You can also configure SENTRY_DSN, SENTRY_RELEASE, SENTRY_DIST, and + // SENTRY_ENVIRONMENT via Dart environment variables (--dart-define). } ``` -## Verify Your Setup +The `appRunner` callback runs in a guarded error zone. This is required for automatic error capture on Dart web, where isolate error listeners are unavailable. For additional isolates, register an error listener with [`addSentryErrorListener`](https://pub.dev/documentation/sentry/latest/sentry_io/SentryIsolateExtension/addSentryErrorListener.html) from `package:sentry/sentry_io.dart`. -Let's test your setup and confirm that data reaches your Sentry project. +For finite command-line applications, call `await Sentry.close()` after all awaited application work finishes to flush buffered telemetry and close SDK resources, including the isolate error-listener port. -### Issues +## Send Logs -To verify that Sentry captures errors and creates issues in your Sentry project, add this intentional error to your application: +Call `Sentry.logger` from your application code after initialization to send structured logs at different levels. You can add attributes to make logs easier to search and filter. + +See Set Up Logs for all available logging methods and message formatting. ```dart -import 'package:sentry/sentry.dart'; +Sentry.logger.info('Order completed', attributes: { + 'order_id': SentryAttribute.string('12345'), + 'total': SentryAttribute.double(99.99), +}); + +Sentry.logger.warn('Slow operation detected'); +Sentry.logger.error('Validation failed'); +``` + +If you use the Dart `logging` package, add the `sentry_logging` integration to send its records to Sentry. + +## Send Application Metrics + +Call `Sentry.metrics` from your application code after initialization to send counters, gauges, and distributions. Add attributes to filter and group metrics in Sentry. + +See Set Up Metrics for metric types, attributes, and configuration options. +```dart +Sentry.metrics.count('checkout.failed', 1); +Sentry.metrics.gauge('queue.depth', 42); +Sentry.metrics.distribution('api_latency', 187, unit: 'millisecond'); +``` + +## Verify Your Setup + +Let's test your setup and confirm that data reaches your Sentry project. + +Add this inside the async `appRunner` callback to trigger and capture a test error: + +```dart try { throw StateError('Sentry Test Error'); } catch (exception, stackTrace) { @@ -87,16 +129,6 @@ try { } ``` - - - - - - - - - - ### View Captured Data in Sentry Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). @@ -105,16 +137,11 @@ Now, head over to your project on [Sentry.io](https://sentry.io) to view the col ## Next Steps -At this point, you should have integrated Sentry into your Dart application and should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. -Our next recommended steps for you are: +At this point, you should have integrated Sentry into your Dart application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Continue to customize your configuration - Learn more about manually capturing errors or messages -- Learn about the features of Sentry's Dart SDK -- Add performance instrumentation to your app +- Add performance instrumentation to your app diff --git a/docs/platforms/dart/guides/flutter/index.mdx b/docs/platforms/dart/guides/flutter/index.mdx index 95d9486c7c9555..ee03b862a1d1a7 100644 --- a/docs/platforms/dart/guides/flutter/index.mdx +++ b/docs/platforms/dart/guides/flutter/index.mdx @@ -1,6 +1,6 @@ --- title: Flutter -description: Learn how to set up Sentry in your Flutter app, capture your first errors and traces, and view them in Sentry. +description: Learn how to set up Sentry in your Flutter app, capture your first events, and view them in Sentry. caseStyle: camelCase supportLevel: production sdk: sentry.dart.flutter @@ -28,34 +28,34 @@ brew install getsentry/tools/sentry-wizard && sentry-wizard -i flutter ``` ```powershell {tabTitle:Windows} -$downloadUrl = "https://github.com/getsentry/sentry-wizard/releases/download/v5.1.0/sentry-wizard-win-x64.exe" +$downloadUrl = "https://github.com/getsentry/sentry-wizard/releases/download/v9.1.0/sentry-wizard-win-x64.exe" Invoke-WebRequest $downloadUrl -OutFile sentry-wizard.exe ./sentry-wizard.exe -i flutter ``` ```bash {tabTitle:macOS (Intel/x64)} -downloadUrl="https://github.com/getsentry/sentry-wizard/releases/download/v5.1.0/sentry-wizard-darwin-x64" +downloadUrl="https://github.com/getsentry/sentry-wizard/releases/download/v9.1.0/sentry-wizard-darwin-x64" curl -L $downloadUrl -o sentry-wizard chmod +x sentry-wizard ./sentry-wizard -i flutter ``` ```bash {tabTitle:macOS (Apple Silicon/arm64)} -downloadUrl="https://github.com/getsentry/sentry-wizard/releases/download/v5.1.0/sentry-wizard-darwin-arm64" +downloadUrl="https://github.com/getsentry/sentry-wizard/releases/download/v9.1.0/sentry-wizard-darwin-arm64" curl -L $downloadUrl -o sentry-wizard chmod +x sentry-wizard ./sentry-wizard -i flutter ``` ```bash {tabTitle:Linux (x64)} -downloadUrl="https://github.com/getsentry/sentry-wizard/releases/download/v5.1.0/sentry-wizard-linux-x64" +downloadUrl="https://github.com/getsentry/sentry-wizard/releases/download/v9.1.0/sentry-wizard-linux-x64" curl -L $downloadUrl -o sentry-wizard chmod +x sentry-wizard ./sentry-wizard -i flutter ``` ```bash {tabTitle:Linux (arm64)} -downloadUrl="https://github.com/getsentry/sentry-wizard/releases/download/v5.1.0/sentry-wizard-linux-arm64" +downloadUrl="https://github.com/getsentry/sentry-wizard/releases/download/v9.1.0/sentry-wizard-linux-arm64" curl -L $downloadUrl -o sentry-wizard chmod +x sentry-wizard ./sentry-wizard -i flutter @@ -65,7 +65,7 @@ chmod +x sentry-wizard npx @sentry/wizard@latest -i flutter ``` -This will patch your project and configure the SDK. You only need to patch the project once, then you can add the patched files to your version control system. +This will patch your project and configure the SDK. **Logs** and **Application Metrics** are enabled by default in SDK v10, and you'll learn how to send them in steps [#2](#send-logs) and [#3](#send-application-metrics-). You only need to patch the project once, then you can add the patched files to your version control system. If you prefer, you can also [set up the SDK manually](/platforms/dart/guides/flutter/manual-setup/). @@ -77,37 +77,47 @@ If you prefer, you can also [set up the SDK manually](/platforms/dart/guides/flu -The wizard will prompt you to enable optional features. Select the same options here so this guide can show you how to verify them: +## Send Logs - +Call `Sentry.logger` from your application code after initialization to send structured logs at different levels. You can add attributes to make logs easier to search and filter. - +See Set Up Logs for all available logging methods and message formatting. -## Verify Your Setup +```dart +Sentry.logger.info('Order completed', attributes: { + 'order_id': SentryAttribute.string('12345'), + 'total': SentryAttribute.double(99.99), +}); -Let's test your setup and confirm that data reaches your Sentry project. +Sentry.logger.warn('Slow operation detected'); +Sentry.logger.error('Validation failed'); +``` -### Issues +If you use the Dart `logging` package, add the `sentry_logging` integration to send its records to Sentry. -The wizard added a sample exception to `main.dart` that is captured when the app starts. Run your app to send it to Sentry: +## Send Application Metrics -```bash -flutter run -``` +Call `Sentry.metrics` from your application code after initialization to send counters, gauges, and distributions. Add attributes to filter and group metrics in Sentry. -After you've confirmed the issue in Sentry, remove the sample exception from `main.dart` so it isn't captured on every launch. +See Set Up Metrics for metric types, attributes, and configuration options. + +```dart +Sentry.metrics.count('checkout.failed', 1); +Sentry.metrics.gauge('queue.depth', 42); +Sentry.metrics.distribution('api_latency', 187, unit: 'millisecond'); +``` - +## Verify Your Setup - +Let's test your setup and confirm that data reaches your Sentry project. - +The wizard added a sample exception to main.dart that is captured when the app starts. Run your app to send it to Sentry: - +```bash +flutter run +``` - +After you've confirmed the issue in Sentry, remove the sample exception from `main.dart` so it isn't captured on every launch. ### View Captured Data in Sentry @@ -117,16 +127,12 @@ Now, head over to your project on [Sentry.io](https://sentry.io) to view the col ## Next Steps -At this point, you should have integrated Sentry into your Flutter application and should already be sending data to your Sentry project. - -Now's a good time to customize your setup and look into more advanced topics. -Our next recommended steps for you are: +At this point, you should have integrated Sentry into your Flutter application. Here's what to explore next: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Continue to customize your configuration -- Add readable stack traces to errors -- Learn about the features of Sentry's Flutter SDK -- Add performance instrumentation to your app +- Upload debug symbols and source maps for readable production stack traces. The wizard configures `sentry_dart_plugin`; run `dart run sentry_dart_plugin` after each production build to upload the files. In CI, provide `SENTRY_AUTH_TOKEN` to the upload step. +- Learn about Session Replay and its privacy controls +- Add performance instrumentation to your app diff --git a/docs/platforms/dart/guides/flutter/manual-setup.mdx b/docs/platforms/dart/guides/flutter/manual-setup.mdx index 01831e8b2c5d4c..33ab575b30990e 100644 --- a/docs/platforms/dart/guides/flutter/manual-setup.mdx +++ b/docs/platforms/dart/guides/flutter/manual-setup.mdx @@ -1,10 +1,14 @@ --- title: Manual Setup sidebar_order: 1 -description: "Learn how to set up the Sentry Flutter SDK manually." +description: "Learn how to manually set up Sentry in your Flutter app, capture your first events, and view them in Sentry." --- -If you can't (or prefer not to) run the [automatic setup](/platforms/dart/guides/flutter/#install), you can follow the instructions below to configure your application manually. + + +Looking for automatic setup with the Flutter wizard? Follow the Flutter Quick Start instead. Continue with this guide to set up the SDK manually. + + @@ -36,19 +40,24 @@ Keep CocoaPods if other plugins still require it. Flutter can use both dependenc ## Configure -Choose the features you want to configure, and this guide will show you how: - - +Initialize **Error Monitoring** with `Sentry.init()` and run your application in its `appRunner` callback to capture uncaught exceptions and unhandled asynchronous errors. **Logs** and **Application Metrics** are enabled by default in SDK v10, and you'll learn how to send them in steps [#3](#send-logs) and [#4](#send-application-metrics-). +This guide also enables **Tracing** and **Session Replay**. ### Initialize the Sentry SDK -Configuration should happen as **early as possible** in your application's lifecycle. Logs and metrics are enabled by default; use `Sentry.logger` and `Sentry.metrics` after initialization without an enable flag. +Configuration should happen as **early as possible** in your application's lifecycle. + +Import and initialize the SDK in your app's entry point as shown in the code snippet below. -Import and initialize the SDK in your app's `main` function: +The snippet also turns on: + +- Tracing: via `tracesSampleRate` +- Session Replay: sampled with `replay.sessionSampleRate` and `replay.onErrorSampleRate` +- Additional user and request data: via `sendDefaultPii` + +To skip tracing, omit `tracesSampleRate`. To skip automatic Session Replay recording, omit both replay sample rates. To discard logs or metrics, return `null` from `beforeSendLog` or `beforeSendMetric`. ```dart import 'package:flutter/widgets.dart'; @@ -58,19 +67,20 @@ Future main() async { await SentryFlutter.init( (options) { options.dsn = '___PUBLIC_DSN___'; - // Adds request headers and IP for users, for more info visit: - // https://docs.sentry.io/platforms/dart/guides/flutter/data-management/data-collected/ + + /// Allows sending default personal data, such as IP addresses, + // when available from the SDK's integrations. options.sendDefaultPii = true; - // ___PRODUCT_OPTION_START___ performance - // Set tracesSampleRate to 1.0 to capture 100% of transactions for tracing. - // We recommend adjusting this value in production. + + // Enables Tracing. + // Set to 1.0 to capture 100% of spans for tracing. + // We recommend reducing this value in production. options.tracesSampleRate = 1.0; - // ___PRODUCT_OPTION_END___ performance - // ___PRODUCT_OPTION_START___ session-replay - // Record session replays for 100% of errors and 10% of sessions + + // Capture replays for 10% of all sessions, + // plus for 100% of sessions with an error options.replay.onErrorSampleRate = 1.0; options.replay.sessionSampleRate = 0.1; - // ___PRODUCT_OPTION_END___ session-replay }, appRunner: () => runApp( SentryWidget( @@ -84,13 +94,41 @@ Future main() async { } ``` +## Send Logs + +Call `Sentry.logger` from your application code after initialization to send structured logs at different levels. You can add attributes to make logs easier to search and filter. + +See Set Up Logs for all available logging methods and message formatting. + +```dart +Sentry.logger.info('Order completed', attributes: { + 'order_id': SentryAttribute.string('12345'), + 'total': SentryAttribute.double(99.99), +}); + +Sentry.logger.warn('Slow operation detected'); +Sentry.logger.error('Validation failed'); +``` + +If you use the Dart `logging` package, add the `sentry_logging` integration to send its records to Sentry. + +## Send Application Metrics + +Call `Sentry.metrics` from your application code after initialization to send counters, gauges, and distributions. Add attributes to filter and group metrics in Sentry. + +See Set Up Metrics for metric types, attributes, and configuration options. + +```dart +Sentry.metrics.count('checkout.failed', 1); +Sentry.metrics.gauge('queue.depth', 42); +Sentry.metrics.distribution('api_latency', 187, unit: 'millisecond'); +``` + ## Verify Your Setup Let's test your setup and confirm that data reaches your Sentry project. -### Issues - -To verify that Sentry captures errors and creates issues in your Sentry project, add this intentional error to your application: +Add this intentional error to your application: ```dart import 'package:sentry_flutter/sentry_flutter.dart'; @@ -105,15 +143,11 @@ try { } ``` - - - - - +Run your app to send the test error to Sentry: - - - +```bash +flutter run +``` ### View Captured Data in Sentry @@ -129,9 +163,7 @@ Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are: - Explore [practical guides](/get-started/guides/) on what to monitor, log, track, and investigate after setup -- Continue to customize your configuration - Add readable stack traces to errors -- Learn about the features of Sentry's Flutter SDK - Add performance instrumentation to your app diff --git a/includes/quick-start-features-expandable.mdx b/includes/quick-start-features-expandable.mdx index 7ecb9d1fdd6976..f1585884326f9b 100644 --- a/includes/quick-start-features-expandable.mdx +++ b/includes/quick-start-features-expandable.mdx @@ -82,6 +82,11 @@ import { FeatureInfo } from "sentry-docs/components/featureInfo"; @@ -91,6 +96,15 @@ import { FeatureInfo } from "sentry-docs/components/featureInfo"; diff --git a/includes/tracing/dart-quick-start-verify-tracing-splitlayout.mdx b/includes/tracing/dart-quick-start-verify-tracing-splitlayout.mdx deleted file mode 100644 index 3ca0aee8a780e8..00000000000000 --- a/includes/tracing/dart-quick-start-verify-tracing-splitlayout.mdx +++ /dev/null @@ -1,10 +0,0 @@ -### Tracing - -To test your tracing configuration, create a custom transaction and span: - -```dart -final transaction = Sentry.startTransaction('test-transaction', 'task'); -final span = transaction.startChild('test-span'); -await span.finish(); -await transaction.finish(); -``` diff --git a/includes/tracing/python-quick-start-verify-tracing-splitlayout.mdx b/includes/tracing/python-quick-start-verify-tracing-splitlayout.mdx deleted file mode 100644 index ecda5df7f65d75..00000000000000 --- a/includes/tracing/python-quick-start-verify-tracing-splitlayout.mdx +++ /dev/null @@ -1,20 +0,0 @@ -### Tracing - -To test your tracing configuration, create a custom transaction and span: - -```py {tabTitle: Transaction Mode (Default)} -import sentry_sdk - -with sentry_sdk.start_transaction(op="task", name="Transaction Name"): - span = sentry_sdk.start_span(name="Custom Span Name") - span.finish() - -``` -```py {tabTitle: Stream Mode} -import sentry_sdk - -with sentry_sdk.traces.start_span(name="Service Span Name", attributes={"sentry.op": "task"}, parent_span=None): - span = sentry_sdk.traces.start_span(name="Custom Span Name") - span.end() - -``` diff --git a/platform-includes/getting-started-prerequisites/dart.mdx b/platform-includes/getting-started-prerequisites/dart.mdx new file mode 100644 index 00000000000000..9675f9bacf075e --- /dev/null +++ b/platform-includes/getting-started-prerequisites/dart.mdx @@ -0,0 +1,8 @@ +## Prerequisites + +These instructions use Sentry Dart SDK v10. You need: + +- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) +- An application using **Dart 3.12.0** or later + +For an existing Sentry integration, review the [v10 breaking changes](https://github.com/getsentry/sentry-dart/releases/tag/10.0.0) before upgrading. diff --git a/src/components/featureInfo.tsx b/src/components/featureInfo.tsx index cc77785831c704..2b46ce8411d2b3 100644 --- a/src/components/featureInfo.tsx +++ b/src/components/featureInfo.tsx @@ -145,6 +145,7 @@ const FEATURE_DATA: Record< type FeatureInfoProps = { features: FeatureKey[]; + overrides?: Partial>; type: 'learnMore' | 'findInSentry'; }; @@ -155,11 +156,11 @@ type FeatureInfoProps = { * @param features - Array of feature keys to display * @param type - learnMore shows feature descriptions, findInSentry shows navigation help */ -export function FeatureInfo({features, type}: FeatureInfoProps) { +export function FeatureInfo({features, overrides, type}: FeatureInfoProps) { return (
    {features.map(key => { - const feature = FEATURE_DATA[key]; + const feature = {...FEATURE_DATA[key], ...overrides?.[key]}; if (type === 'learnMore') { return (