diff --git a/docs/platforms/apple/guides/ios/manual-setup.mdx b/docs/platforms/apple/guides/ios/manual-setup.mdx index 5a42410fa36ae..7f1ad3f48d5be 100644 --- a/docs/platforms/apple/guides/ios/manual-setup.mdx +++ b/docs/platforms/apple/guides/ios/manual-setup.mdx @@ -98,3 +98,42 @@ struct SwiftUIApp: App { } } ``` + +## Add Readable Stack Traces With Debug Symbols + +To get readable stack traces for release builds, upload dSYM files to Sentry during your Xcode build. Add `--include-sources` to upload source context at the same time, so Sentry can show code snippets next to stack frames. + +1. Install [Sentry CLI](/cli/installation/). +2. Configure Sentry CLI authentication. Use `SENTRY_AUTH_TOKEN` in your CI/CD environment, or use a local `.sentryclirc` file and add it to `.gitignore`. +3. In your app target build settings, set `DEBUG_INFORMATION_FORMAT` to `DWARF with dSYM File` and `ENABLE_USER_SCRIPT_SANDBOXING` to `NO` for the configurations that should upload debug symbols. +4. Add a new Xcode Run Script build phase named `Upload Debug Symbols to Sentry`: + + + +```bash +# This script is responsible for uploading debug symbols and source context for Sentry. +if [[ "$(uname -m)" == arm64 ]]; then + export PATH="/opt/homebrew/bin:$PATH" +fi + +if which sentry-cli >/dev/null; then + export SENTRY_ORG=___ORG_SLUG___ + export SENTRY_PROJECT=___PROJECT_SLUG___ + ERROR=$(sentry-cli debug-files upload --include-sources "$DWARF_DSYM_FOLDER_PATH" 2>&1 >/dev/null) + if [ ! $? -eq 0 ]; then + echo "warning: sentry-cli - $ERROR" + fi +else + echo "warning: sentry-cli not installed, download from https://github.com/getsentry/sentry-cli/releases" +fi +``` + +5. Add this path to the Run Script's **Input Files**: + +```text +${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${TARGET_NAME} +``` + +If you don't want to upload source code, remove the `--include-sources` argument from the Run Script. + +For more details, see Uploading Debug Symbols and Source Context. diff --git a/docs/platforms/dart/guides/flutter/index.mdx b/docs/platforms/dart/guides/flutter/index.mdx index d12c2a3c628ef..dc000e30e6bb1 100644 --- a/docs/platforms/dart/guides/flutter/index.mdx +++ b/docs/platforms/dart/guides/flutter/index.mdx @@ -31,11 +31,11 @@ Select which Sentry features you'd like to install in addition to Error Monitori @@ -92,6 +92,8 @@ If you prefer, you can also [set up the SDK manually](/platforms/dart/guides/flu - Configure the SDK with your DSN and performance monitoring options in your main.dart file. - Update your `pubspec.yaml` with the `sentry_flutter` and `sentry_dart_plugin` packages. +- Add Sentry Dart Plugin configuration for debug symbol uploads. +- Create `sentry.properties` with an auth token for local uploads (this file is automatically added to `.gitignore`). - Add an example error to verify your setup. @@ -165,6 +167,12 @@ try { ## Next Steps - Explore [practical guides](/guides/) on what to monitor, log, track, and investigate after setup -- Learn about the features of Sentry's Flutter SDK -- Add readable stack traces to errors -- Add performance instrumentation to your app +- + Learn about the features of Sentry's Flutter SDK + +- + Add readable stack traces to errors + +- + 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 cbf07999b9b45..a6df2184cbe1c 100644 --- a/docs/platforms/dart/guides/flutter/manual-setup.mdx +++ b/docs/platforms/dart/guides/flutter/manual-setup.mdx @@ -9,12 +9,7 @@ If you can't (or prefer not to) run the [automatic setup](/platforms/dart/guides ## Install Sentry captures data by using an SDK within your application's runtime. These are platform-specific and allow Sentry to have a deep understanding of how your application works. @@ -67,6 +62,55 @@ Future main() async { } ``` +## Add Readable Stack Traces With Debug Symbols + +To get readable stack traces for obfuscated Flutter builds and native frames, configure the Sentry Dart Plugin to upload debug symbols during your release workflow. + +1. Add `sentry_dart_plugin` as a dev dependency: + +```yml {filename:pubspec.yaml} +dev_dependencies: + sentry_dart_plugin: ^{{@inject packages.version('sentry.dart.plugin', '2.0.0') }} +``` + +2. Add the non-secret plugin configuration to `pubspec.yaml`: + +```yml {filename:pubspec.yaml} +sentry: + upload_debug_symbols: true + upload_source_maps: true + project: ___PROJECT_SLUG___ + org: ___ORG_SLUG___ +``` + +3. Configure Sentry auth for local builds with an ignored `sentry.properties` file, or set `SENTRY_AUTH_TOKEN` in your CI/CD environment: + + + +```properties {filename:sentry.properties} +auth_token=___ORG_AUTH_TOKEN___ +``` + +```text {filename:.gitignore} +sentry.properties +``` + +4. For production builds, build with debug information and then run the plugin: + +```bash +flutter build --obfuscate --split-debug-info=build/debug-info +flutter pub run sentry_dart_plugin +``` + +For Flutter Web, build with source maps before running the plugin: + +```bash +flutter build web --release --source-maps +flutter pub run sentry_dart_plugin +``` + +For more details, see Sentry Dart Plugin. + ## Verify Verify that your app is sending events to Sentry by adding the following snippet, which includes an intentional error. You should see the error reported in Sentry within a few minutes. @@ -86,6 +130,12 @@ try { ## Next Steps -- Learn about the features of Sentry's Flutter SDK -- Add readable stack traces to errors -- Add performance instrumentation to your app +- + Learn about the features of Sentry's Flutter SDK + +- + Add readable stack traces to errors + +- + Add performance instrumentation to your app +