Skip to content

Commit bfd7af3

Browse files
Fiona2016claude
andcommitted
docs(rum): say that Flutter iOS Dart stacks are not symbolicated
The symbolication tables listed a single `Dart` row pointing at Flutter symbols, with no platform qualifier, so they read as a promise that iOS Dart frames resolve the same way Android ones do. They do not: the `.symbols` file Flutter produces for iOS carries no build id (flutter/flutter#138182, open since 2023), so it cannot be matched to a build and the upload rejects it. The omission cost more than a failed upload. Readers following these pages ran `--obfuscate` on their iOS builds, and with no uploadable symbol file nothing can ever un-rename those symbols -- so the Dart stacks they were trying to make readable became permanently unreadable instead. Split the Dart row by platform and add the reason, the `--obfuscate` warning, and the note that iOS native crashes are unaffected and still symbolicate from dSYMs. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 parent fa29fa5 commit bfd7af3

4 files changed

Lines changed: 24 additions & 4 deletions

File tree

en/rum/sdk/flutter/advanced-config.mdx

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,10 +88,15 @@ To resolve crash and error stacks back to source locations, you need to upload s
8888

8989
| Frame type | Required files | How to generate |
9090
|----------|----------|----------|
91-
| Dart | Flutter symbols | `flutter build --split-debug-info=<dir> --obfuscate` |
91+
| Dart (Android) | Flutter symbols | `flutter build apk --split-debug-info=<dir> --obfuscate` |
92+
| Dart (iOS) | Not supported yet, see the note below ||
9293
| iOS Native | dSYM | Xcode build output |
9394
| Android Native | mapping files | R8 / ProGuard output |
9495

96+
<Warning>
97+
**Dart stacks cannot be symbolicated on iOS yet.** The `.symbols` file Flutter produces for iOS carries no build id ([flutter/flutter#138182](https://github.com/flutter/flutter/issues/138182)), so it cannot be matched to a build and cannot be uploaded. Do not enable `--obfuscate` for iOS builds, or your Dart stacks will be unrecoverable. iOS native crashes are unaffected — upload dSYMs to symbolicate them.
98+
</Warning>
99+
95100
Use the FlashCat CLI to upload symbol files:
96101

97102
```bash

en/rum/sdk/flutter/compatible.mdx

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,10 +60,15 @@ Flutter crash stacks can contain both Dart frames and native (iOS / Android) fra
6060

6161
| Frame type | Required uploaded files |
6262
|----------|--------------|
63-
| Dart | Flutter symbols (`flutter build --split-debug-info` output) |
63+
| Dart (Android) | Flutter symbols (`flutter build --split-debug-info` output) |
64+
| Dart (iOS) | Not supported yet, see the note below |
6465
| iOS Native | dSYM |
6566
| Android Native | mapping files |
6667

68+
<Warning>
69+
**Dart stacks cannot be symbolicated on iOS yet.** The `.symbols` file Flutter produces for iOS carries no build id ([flutter/flutter#138182](https://github.com/flutter/flutter/issues/138182)), so it cannot be matched to a build and cannot be uploaded. Do not enable `--obfuscate` for iOS builds, or your Dart stacks will be unrecoverable. iOS native crashes are unaffected — upload dSYMs to symbolicate them.
70+
</Warning>
71+
6772
<Tip>
6873
Symbol files are uploaded through the FlashCat CLI, and the `version` used at upload time must match the `version` in the SDK initialization. Otherwise the console can receive crash events but cannot resolve the stacks.
6974
</Tip>

zh/rum/sdk/flutter/advanced-config.mdx

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,10 +88,15 @@ DatadogRumConfiguration(
8888

8989
| 栈帧类型 | 所需文件 | 生成方式 |
9090
|----------|----------|----------|
91-
| Dart | Flutter symbols | `flutter build --split-debug-info=<dir> --obfuscate` |
91+
| Dart(Android) | Flutter symbols | `flutter build apk --split-debug-info=<dir> --obfuscate` |
92+
| Dart(iOS) | 暂不支持,见下方说明 ||
9293
| iOS Native | dSYM | Xcode 构建产物 |
9394
| Android Native | mapping 文件 | R8 / ProGuard 产物 |
9495

96+
<Warning>
97+
**iOS 的 Dart 堆栈暂不支持符号化。** Flutter 为 iOS 生成的 `.symbols` 不包含 build id([flutter/flutter#138182](https://github.com/flutter/flutter/issues/138182)),无法与具体构建对应,因此无法上传使用。iOS 构建请勿开启 `--obfuscate`,否则 Dart 堆栈将无法还原。iOS 原生崩溃不受影响,上传 dSYM 即可符号化。
98+
</Warning>
99+
95100
使用 FlashCat CLI 上传符号文件:
96101

97102
```bash

zh/rum/sdk/flutter/compatible.mdx

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,10 +60,15 @@ Flutter 崩溃栈可能同时包含 Dart 帧与原生(iOS / Android)帧。
6060

6161
| 栈帧类型 | 所需上传文件 |
6262
|----------|--------------|
63-
| Dart | Flutter symbols(`flutter build --split-debug-info` 产物) |
63+
| Dart(Android) | Flutter symbols(`flutter build --split-debug-info` 产物) |
64+
| Dart(iOS) | 暂不支持,见下方说明 |
6465
| iOS Native | dSYM |
6566
| Android Native | mapping 文件 |
6667

68+
<Warning>
69+
**iOS 的 Dart 堆栈暂不支持符号化。** Flutter 为 iOS 生成的 `.symbols` 不包含 build id([flutter/flutter#138182](https://github.com/flutter/flutter/issues/138182)),无法与具体构建对应,因此无法上传使用。iOS 构建请勿开启 `--obfuscate`,否则 Dart 堆栈将无法还原。iOS 原生崩溃不受影响,上传 dSYM 即可符号化。
70+
</Warning>
71+
6772
<Tip>
6873
符号文件通过 FlashCat CLI 上传,且上传时的 `version` 必须与 SDK 初始化中的 `version` 一致,否则控制台可以收到崩溃事件,但无法还原堆栈。
6974
</Tip>

0 commit comments

Comments
 (0)