Skip to content

Commit 06762b4

Browse files
buenaflorbuenaflor
authored
chore(readme): Update README to reference sentry docs page (#378)
* Revise README with installation and usage details Updated the README to include installation and usage instructions for the sentry_dart_plugin, along with configuration details and breaking changes in version 3.0.0. * Update README
1 parent 4c73221 commit 06762b4

File tree

1 file changed

+2
-203
lines changed

1 file changed

+2
-203
lines changed

‎README.md‎

Lines changed: 2 additions & 203 deletions
Original file line numberDiff line numberDiff line change
@@ -6,207 +6,6 @@
66

77
A 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/).
88

9-
For doing it manually, please follow our [docs](https://docs.sentry.io/platforms/flutter/upload-debug/).
9+
## Installation and Usage
1010

11-
## :clipboard: Install
12-
13-
In your `pubspec.yaml`, add `sentry_dart_plugin` as a new dev dependency.
14-
15-
```yaml
16-
dev_dependencies:
17-
sentry_dart_plugin: ^3.0.0
18-
```
19-
20-
## Build App
21-
22-
The `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.
23-
24-
## Run
25-
26-
```bash
27-
dart run sentry_dart_plugin
28-
```
29-
30-
## Configuration (Optional)
31-
32-
This tool comes with a default configuration. You can configure it to suit your needs.
33-
By default the plugin will look for the Sentry configuration in the `pubspec.yaml` and `sentry.properties` file.
34-
If a Sentry value does not exist in `pubspec.yaml`, the plugin will fallback to `sentry.properties` file.
35-
If a value exists in both, the `pubspec.yaml` takes precedence over the `sentry.properties` values.
36-
Environment and argument variables will take precedence over the file based ones.
37-
38-
### pubspec.yaml
39-
40-
Add `sentry:` configuration at the end of your `pubspec.yaml` file:
41-
42-
```yaml
43-
sentry:
44-
upload_debug_symbols: true
45-
upload_source_maps: false
46-
upload_sources: false
47-
legacy_web_symbolication: false
48-
project: ...
49-
org: ...
50-
auth_token: ...
51-
url: ...
52-
url_prefix: ...
53-
wait_for_processing: false
54-
log_level: error # possible values: trace, debug, info, warn, error
55-
release: ...
56-
dist: ...
57-
build_path: ...
58-
web_build_path: ...
59-
symbols_path: ...
60-
# Path to the Dart obfuscation map (opt-in)
61-
# Example generation flags:
62-
# flutter build apk --obfuscate --split-debug-info=symbols \\
63-
# --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json
64-
# Then set the path below to the generated obfuscation map file
65-
dart_symbol_map_path: build/app/obfuscation.map.json
66-
commits: auto
67-
ignore_missing: true
68-
```
69-
70-
You can also override or extend your file based configuration by passing the parameters as arguments
71-
in the format `--sentry-define=<KEY>=<VALUE>`. They take precedence over your file based parameters,
72-
but not over the alternative environment variables.
73-
74-
```bash
75-
dart run sentry_dart_plugin --sentry-define=release=app-internal-test@0.0.1
76-
```
77-
78-
### sentry.properties
79-
80-
Create a `sentry.properties` file at the root of your project:
81-
82-
```properties
83-
upload_debug_symbols=true
84-
upload_source_maps=false
85-
upload_sources=false
86-
legacy_web_symbolication=false
87-
project=...
88-
org=...
89-
auth_token=...
90-
url=...
91-
wait_for_processing=false
92-
log_level=error # possible values: trace, debug, info, warn, error
93-
release=...
94-
dist=...
95-
build_path: ...
96-
web_build_path=...
97-
symbols_path=...
98-
commits=auto
99-
ignore_missing=true
100-
```
101-
102-
### Available Configuration Fields
103-
104-
| Configuration Name | Description | Default Value And Type | Required | Alternative Environment variable |
105-
| ------------------------ |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ------------------------------------------------------------- | -------- | -------------------------------- |
106-
| upload_debug_symbols | Enables or disables the automatic upload of debug symbols | true (boolean) | no | - |
107-
| upload_source_maps | Enables or disables the automatic upload of source maps | false (boolean) | no | - |
108-
| upload_sources | Does or doesn't include the source code of native code | false (boolean) | no | - |
109-
| legacy_web_symbolication | Uses legacy symbolication method for Flutter Web instead of Debug IDs | false (boolean) | no | - |
110-
| project | Project's name | e.g. sentry-flutter (string) | yes | SENTRY_PROJECT |
111-
| org | Organization's slug | e.g. sentry-sdks (string) | yes | SENTRY_ORG |
112-
| auth_token | Auth Token | e.g. 64 random characteres (string) | yes | SENTRY_AUTH_TOKEN |
113-
| url | URL | e.g. https<area>://mysentry.invalid/ (string) | no | SENTRY_URL |
114-
| url_prefix | URL prefix for JS source maps | e.g. ~/app/ (string) | no | - |
115-
| wait_for_processing | Wait for server-side processing of uploaded files | false (boolean) | no | - |
116-
| log_level | Configures the log level for sentry-cli | warn (string) | no | SENTRY_LOG_LEVEL |
117-
| release | The release version for source maps, it should match the release set by the SDK | name@version from pubspec (string) | no | SENTRY_RELEASE |
118-
| 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 |
119-
| build_path | The build folder of debug files for upload | `build` (string) | no | - |
120-
| web_build_path | The web build folder of debug files for upload relative to build_path | `web` (string) | no | - |
121-
| symbols_path | The directory containing debug symbols (i.e. the `--split-debug-info=` parameter value you pass to `flutter build`) | `.` (string) | no | - |
122-
| dart_symbol_map_path | Absolute or relative path to a Dart obfuscation map file to upload. This allows symbolication of Flutter issue titles for Android and iOS. The map file is generated by adding the following arguments to your Flutter build command: `--extra-gen-snapshot-options=--save-obfuscation-map=<path>`. | null (string) | no | - |
123-
| commits | Release commits integration | auto (string) | no | - |
124-
| ignore_missing | Ignore missing commits previously used in the release | false (boolean) | no | - |
125-
| bin_dir | The folder where the plugin downloads the sentry-cli binary | .dart_tool/pub/bin/sentry_dart_plugin (string) | no | - |
126-
| bin_path | Path to the sentry-cli binary to use instead of downloading. Make sure to use the correct version. | null (string) | no | - |
127-
| sentry_cli_cdn_url | Alternative place to download sentry-cli | https://downloads.sentry-cdn.com/sentry-cli (string) | no | SENTRYCLI_CDNURL |
128-
| sentry_cli_version | Override the sentry-cli version that should be downloaded. | (string) | no | - |
129-
130-
## Breaking Changes in v3.0.0
131-
132-
### Debug IDs for Flutter Web
133-
134-
Starting with version 3.0.0, the plugin now automatically embeds [Debug IDs](https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/debug-ids/) into your generated source maps for Flutter Web by default. This makes symbolication of Flutter Web stack traces far more stable and reliable.
135-
136-
**Important:** Debug IDs only work with **Sentry Flutter SDK 9.1.0 or newer**. If you're using an older version of the Sentry Flutter SDK (9.0.0 or below), you have two options:
137-
138-
1. **Recommended:** Upgrade to Sentry Flutter SDK 9.1.0 or newer to use Debug IDs
139-
2. **Legacy mode:** Add the following to your configuration to use the classic symbolication method:
140-
141-
```yaml
142-
sentry:
143-
legacy_web_symbolication: true
144-
```
145-
146-
## Release
147-
148-
Per default, the release is build from pubspec.yaml's name, version & build: `name@version+build`. The build number, if present, is used as the `dist` parameter.
149-
150-
You 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.
151-
A custom `dist` value will also be used as the build number.
152-
153-
If 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`.
154-
155-
## Web
156-
157-
If you're publishing your app on the web and it's not deployed at the root of your URL, you need to configure a `url_prefix` and update your stack frames.
158-
159-
Add the prefix to your `pubspec.yaml` in addition to your other configurations. Make sure that you have `upload_source_maps` enabled:
160-
161-
```properties
162-
sentry:
163-
upload_source_maps=true
164-
url_prefix: ~/your_prefix/
165-
```
166-
167-
The 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:
168-
169-
```dart
170-
options.beforeSend = (event, hint) async {
171-
final exceptions = event.exceptions?.map((exception) {
172-
final stackTrace = exception.stackTrace;
173-
if (stackTrace != null) {
174-
final frames = stackTrace.frames.map((frame) {
175-
const baseUrl = 'https://your-domain.com/';
176-
final modifiedAbsPath = frame.absPath?.replaceFirst(
177-
baseUrl,
178-
'${baseUrl}your_prefix/',
179-
);
180-
return frame.copyWith(absPath: modifiedAbsPath);
181-
}).toList();
182-
return exception.copyWith(
183-
stackTrace: SentryStackTrace(frames: frames),
184-
);
185-
}
186-
return exception;
187-
}).toList();
188-
return event.copyWith(exceptions: exceptions ?? []);
189-
};
190-
```
191-
192-
Don't forget to specify the prefix path when building for the web and also build with `--source-maps`:
193-
194-
```bash
195-
flutter build web --base-href=/your_prefix/ --source-maps
196-
```
197-
198-
## Troubleshooting
199-
200-
Sentry's `auth_token` requires the `project:releases` or `project:write` scope, See [docs](https://docs.sentry.io/product/cli/dif/#permissions).
201-
202-
For the `commits` feature, Sentry's `auth_token` also requires the `org:read` scope, See [docs](https://docs.sentry.io/api/permissions/#releases).
203-
204-
Dart'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).
205-
206-
The `--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).
207-
208-
Flutter'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)
209-
210-
If you opt into uploading a Dart obfuscation map (`dart_symbol_map_path`), ensure you build with both `--obfuscate` and `--extra-gen-snapshot-options=--save-obfuscation-map=<path>`. The map path you configure must point to the generated file.
211-
212-
If 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)
11+
Please refer to [Sentry Dart Plugin's documentation page](https://docs.sentry.io/platforms/dart/guides/flutter/debug-symbols/).

0 commit comments

Comments
 (0)