{"id":13549715,"url":"https://github.com/getsentry/sentry-dart-plugin","last_synced_at":"2025-04-05T04:08:57.732Z","repository":{"id":40646061,"uuid":"398188119","full_name":"getsentry/sentry-dart-plugin","owner":"getsentry","description":"A Dart Build Plugin that uploads debug symbols for Android, iOS/macOS and source maps for Web to Sentry via sentry-cli","archived":false,"fork":false,"pushed_at":"2025-03-28T03:18:04.000Z","size":54945,"stargazers_count":69,"open_issues_count":16,"forks_count":31,"subscribers_count":44,"default_branch":"main","last_synced_at":"2025-03-30T21:32:50.503Z","etag":null,"topics":["crash-reporting","dart","flutter","hacktoberfest","sentry","tag-production","team-mobile"],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/getsentry.png","metadata":{"funding":{"custom":["https://sentry.io/pricing/","https://sentry.io/"]},"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-20T07:09:43.000Z","updated_at":"2025-02-21T14:19:56.000Z","dependencies_parsed_at":"2023-02-16T18:16:06.064Z","dependency_job_id":"81af7424-d115-4d3f-8952-6e0825a66327","html_url":"https://github.com/getsentry/sentry-dart-plugin","commit_stats":{"total_commits":91,"total_committers":14,"mean_commits":6.5,"dds":0.7362637362637363,"last_synced_commit":"9ff433665be0fcd651c990dc1aa2070ac3a6ba1c"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Fsentry-dart-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Fsentry-dart-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Fsentry-dart-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Fsentry-dart-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getsentry","download_url":"https://codeload.github.com/getsentry/sentry-dart-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247284945,"owners_count":20913704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crash-reporting","dart","flutter","hacktoberfest","sentry","tag-production","team-mobile"],"created_at":"2024-08-01T12:01:24.721Z","updated_at":"2025-04-05T04:08:57.669Z","avatar_url":"https://github.com/getsentry.png","language":"Dart","readme":"# Sentry Dart Plugin\n\n[![Sentry Dart Plugin](https://github.com/getsentry/sentry-dart-plugin/actions/workflows/dart_plugin.yml/badge.svg)](https://github.com/getsentry/sentry-dart-plugin/actions/workflows/dart_plugin.yml)\n[![pub package](https://img.shields.io/pub/v/sentry_dart_plugin.svg)](https://pub.dev/packages/sentry_dart_plugin)\n[![pub points](https://img.shields.io/pub/points/sentry_dart_plugin)](https://pub.dev/packages/sentry_dart_plugin/score)\n\nA Dart Build Plugin that uploads debug symbols for Android, iOS/macOS and source maps for Web to Sentry via [sentry-cli](https://docs.sentry.io/product/cli/).\n\nFor doing it manually, please follow our [docs](https://docs.sentry.io/platforms/flutter/upload-debug/).\n\n## :clipboard: Install\n\nIn your `pubspec.yaml`, add `sentry_dart_plugin` as a new dev dependency.\n\n```yaml\ndev_dependencies:\n  sentry_dart_plugin: ^2.0.0\n```\n\n## Build App\n\nThe `flutter build apk`, `flutter build ios` (or _macos_) or `flutter build web` is required before executing the `sentry_dart_plugin` plugin, because the build spits out the debug symbols and source maps.\n\n## Run\n\n```bash\ndart run sentry_dart_plugin\n```\n\n## Configuration (Optional)\n\nThis tool comes with a default configuration. You can configure it to suit your needs.\nBy default the plugin will look for the Sentry configuration in the `pubspec.yaml` and `sentry.properties` file.\nIf a Sentry value does not exist in `pubspec.yaml`, the plugin will fallback to `sentry.properties` file.\nIf a value exists in both, the `pubspec.yaml` takes precedence over the `sentry.properties` values.\nEnvironment and argument variables will take precedence over the file based ones.\n\n### pubspec.yaml\n\nAdd `sentry:` configuration at the end of your `pubspec.yaml` file:\n\n```yaml\nsentry:\n  upload_debug_symbols: true\n  upload_source_maps: false\n  upload_sources: false\n  project: ...\n  org: ...\n  auth_token: ...\n  url: ...\n  wait_for_processing: false\n  log_level: error # possible values: trace, debug, info, warn, error\n  release: ...\n  dist: ...\n  build_path: ...\n  web_build_path: ...\n  symbols_path: ...\n  commits: auto\n  ignore_missing: true\n```\n\nYou can also override or extend your file based configuration by passing the parameters as arguments\nin the format `--sentry-define=\u003cKEY\u003e=\u003cVALUE\u003e`. They take precedence over your file based parameters,\nbut not over the alternative environment variables.\n\n```bash\ndart run sentry_dart_plugin --sentry-define=release=app-internal-test@0.0.1\n```\n\n### sentry.properties\n\nCreate a `sentry.properties` file at the root of your project:\n\n```properties\nupload_debug_symbols=true\nupload_source_maps=false\nupload_sources=false\nproject=...\norg=...\nauth_token=...\nurl=...\nwait_for_processing=false\nlog_level=error # possible values: trace, debug, info, warn, error\nrelease=...\ndist=...\nbuild_path: ...\nweb_build_path=...\nsymbols_path=...\ncommits=auto\nignore_missing=true\n```\n\n### Available Configuration Fields\n\n| Configuration Name | Description | Default Value And Type | Required | Alternative Environment variable |\n| - | - | - | - | - |\n| upload_debug_symbols | Enables or disables the automatic upload of debug symbols | true (boolean) | no | - |\n| upload_source_maps | Enables or disables the automatic upload of source maps | false (boolean) | no | - |\n| upload_sources | Does or doesn't include the source code of native code | false (boolean) | no | - |\n| project | Project's name | e.g. sentry-flutter (string) | yes | SENTRY_PROJECT |\n| org | Organization's slug | e.g. sentry-sdks (string) | yes | SENTRY_ORG |\n| auth_token | Auth Token | e.g. 64 random characteres (string)  | yes | SENTRY_AUTH_TOKEN |\n| url | URL | e.g. https\u003carea\u003e://mysentry.invalid/ (string)  | no | SENTRY_URL |\n| url_prefix | URL prefix for JS source maps | e.g. ~/app/ (string) | no | - |\n| wait_for_processing | Wait for server-side processing of uploaded files | false (boolean)  | no | - |\n| log_level | Configures the log level for sentry-cli | warn (string)  | no | SENTRY_LOG_LEVEL |\n| release | The release version for source maps, it should match the release set by the SDK | name@version from pubspec (string)  | no | SENTRY_RELEASE |\n| dist | The dist/build number for source maps, it should match the dist set by the SDK | the number after the '+' char from 'version' pubspec (string)  | no | SENTRY_DIST |\n| build_path | The build folder of debug files for upload | `build` (string)  | no | - |\n| web_build_path | The web build folder of debug files for upload relative to build_path | `web` (string) | no | - |\n| symbols_path | The directory containing debug symbols (i.e. the `--split-debug-info=` parameter value you pass to `flutter build`) | `.` (string) | no | - |\n| commits | Release commits integration | auto (string) | no | - |\n| ignore_missing | Ignore missing commits previously used in the release | false (boolean) | no | - |\n| bin_dir | The folder where the plugin downloads the sentry-cli binary | .dart_tool/pub/bin/sentry_dart_plugin (string) | no | - |\n| bin_path | Path to the sentry-cli binary to use instead of downloading. Make sure to use the correct version. | null (string) | no | - |\n| sentry_cli_cdn_url | Alternative place to download sentry-cli | https://downloads.sentry-cdn.com/sentry-cli (string) | no | SENTRYCLI_CDNURL |\n| sentry_cli_version | Override the sentry-cli version that should be downloaded. | (string) | no | - |\n\n## Release\n\nPer default, the release is build from pubspec.yaml's name, version \u0026 build: `name@version+build`. The build number, if present, is used as the `dist` parameter.\n\nYou can override these values by providing a `release` and `dist` through the plugin config, or through environmental values. The latter have precedence over the former.\nA custom `dist` value will also be used as the build number.\n\nIf provided, the plugin will take your `release` and `dist` values without further mutating them. Make sure you configure everything as outlined in the [release docs](https://docs.sentry.io/product/cli/releases/) of `sentry-cli`.\n\n## Web\n\nIf you're publishing your app on the web and it's not deployed at the root of your URL, you need to configure a `prefix` and update your stack frames.\n\nAdd the prefix to your `pubspec.yaml` in addition to your other configurations. Make sure that you have `upload_source_maps` enabled:\n\n```properties\nsentry:\n  upload_source_maps=true\n  prefix: ~/your_prefix/\n```\n\nThe absolute path of your stack frames also needs to include the same prefix so that the source maps can be found for deobfuscation. Below is an example of how to update the stack frame's absolute path to include the prefix using the `beforeSend` hook:\n\n```dart\noptions.beforeSend = (event, hint) async {\n  final exceptions = event.exceptions?.map((exception) {\n    final stackTrace = exception.stackTrace;\n    if (stackTrace != null) {\n      final frames = stackTrace.frames.map((frame) {\n        const baseUrl = 'https://your-domain.com/';\n        final modifiedAbsPath = frame.absPath?.replaceFirst(\n          baseUrl,\n          '${baseUrl}your_prefix/',\n        );\n        return frame.copyWith(absPath: modifiedAbsPath);\n      }).toList();\n      return exception.copyWith(\n        stackTrace: SentryStackTrace(frames: frames),\n      );\n    }\n    return exception;\n  }).toList();\n  return event.copyWith(exceptions: exceptions ?? []);\n};\n```\n\nDon't forget to specify the prefix path when building for the web and also build with `--source-maps`:\n\n```bash\nflutter build web --base-href=/your_prefix/ --source-maps\n```\n\n## Troubleshooting\n\nSentry's `auth_token` requires the `project:releases` or `project:write` scope, See [docs](https://docs.sentry.io/product/cli/dif/#permissions).\n\nFor the `commits` feature, Sentry's `auth_token` also requires the `org:read` scope, See [docs](https://docs.sentry.io/api/permissions/#releases).\n\nDart's `--obfuscate` option is required to be paired with `--split-debug-info` to generate a symbol map, See [docs](https://github.com/flutter/flutter/wiki/Obfuscating-Dart-Code).\n\nThe `--split-debug-info` option requires setting a output directory, the directory must be an inner folder of the project's folder, See [docs](https://flutter.dev/docs/deployment/obfuscate#obfuscating-your-app).\n\nFlutter's `build web` command requires setting the `--source-maps` parameter to generate source maps, See [Issue](https://github.com/flutter/flutter/issues/72150#issuecomment-755541599)\n\nIf a previous release could not be found in the git history, please make sure you set `ignore_missing: true` in the configuration if you want to ignore such errors, See [Issue](https://github.com/getsentry/sentry-dart-plugin/issues/153)\n","funding_links":["https://sentry.io/pricing/","https://sentry.io/"],"categories":["Dart"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetsentry%2Fsentry-dart-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetsentry%2Fsentry-dart-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetsentry%2Fsentry-dart-plugin/lists"}