诊断、日志和错误报告

每个 Tracelet 应用程序都会记录 SDK 在设备上执行的操作 — 权限、跟踪状态、传感器可用性和滚动日志。这 tracelet_doctor 包将所有这些变成 一键诊断屏幕和复制粘贴错误报告，所以当有些事情看起来不对劲，您（或您的用户）可以准确地捕捉到发生的情况。

3.3.0 中的新增功能： 医生的复制按钮现在捆绑了一切（运行状况 + 配置 + 日志 + 远程信息处理）到单个 Markdown 报告中，以及新的“共享”按钮可让您将其作为 .md 文件下载/通过电子邮件发送。还有一个日志查看器中的 复制日志 按钮。

30秒版本

添加 tracelet_doctor 作为 开发依赖项 （不是常规依赖项） - 这是一种调试工具，Flutter 从发布版本中排除开发依赖包：


flutter pub add dev:tracelet_doctor

然后保护 kDebugMode 后面的使用，以便从发布版本中进行树摇动：


import 'package:flutter/foundation.dart' show kDebugMode;
import 'package:tracelet_doctor/tracelet_doctor.dart';
 
// Open the diagnostic screen from a debug menu, button, or shake gesture:
if (kDebugMode) {
  TraceletDoctor.show(context);
}

这将打开一个工作表：

警告 - 任何可能损害跟踪的内容（权限被拒绝、省电模式、激进的 OEM、无显着运动传感器、模拟位置……）。
权限、跟踪状态、电池和 OEM、配置、传感器、数据库。
查看日志 按钮（最后 500 条日志行）。
复制错误报告 和 分享错误报告 按钮位于右上角。

提交错误报告（为您的用户）

当用户报告问题时，帮助他们的最快方法是获取 Tracelet 错误报告。告诉他们：

打开 Tracelet Doctor 屏幕（无论您将其放置在应用程序中的哪个位置）。
点击右上角的共享图标 (↗) — 或复制 (⧉)。
将其粘贴/附加到您的支持频道或 GitHub 问题中，连同与您自己的任何应用程序日志。

该报告是纯 Markdown 形式，如下所示：


# Tracelet Bug Report
 
_Generated by Tracelet Doctor at 2026-06-14T10:22:31Z (UTC)._
 
## Health check
| Field | Value |
|---|---|
| Platform | android |
| OS version | 14 |
| Manufacturer | Xiaomi |
| Aggressive OEM | true (rating 5/5) |
| Location permission | always |
| Power save mode | true |
...
**Warnings (2):**
- ⚠️ Power Save mode is ON — may throttle background tracking
- ⚠️ Device manufacturer may kill background apps
 
## Active configuration
```json
{ “geo”：{ “distanceFilter”：10.0，... }，
"http": { "url": "《编辑》", "headers": "《编辑》", ... } }
```
 
## Telematics events (most recent)
| Type | Severity | Lat | Lng | Time | Synced |
...
 
## Logs (last 500)
2026-06-14T10:21:55Z [INFO] Tracking started (mode: location)
2026-06-14T10:22:03Z [WARN] Location accuracy degraded
...

秘密会自动编辑。 在将配置添加到报告，其键类似于 URL、标头、参数、键、令牌或证书被替换为 «redacted»。您的同步 URL、API 密钥和身份验证标题永远不会出现在粘贴的报告中。（其他一切 - 距离过滤器，准确性、功能切换 - 被保留，因为这有助于调试。）

直接使用日志

Doctor 读取的日志与您可以从 API 访问的日志相同。这很方便，如果你想要构建您自己的诊断屏幕或将日志发送到您的后端。


// Read the most recent log entries.
final logs = await Tracelet.getLogs(500);
for (final entry in logs) {
  print('${entry.timestamp} [${entry.level}] ${entry.message}');
}
 
// Wipe stored logs (e.g. after the user files a report).
await Tracelet.clearLogs();

每个LogEntry都有id、level（DEBUG/INFO/WARN/ERROR）、message、和 ISO-8601 NOTTRANS0LATE。日志存储在设备上的 SQLite 数据库中，因此它们在应用程序重新启动后仍能幸存并捕获后台活动 - 正是否则无法在调试器中看到的事件。

记录多少由您的 LoggerConfig（日志级别）控制。降低生产水平保持数据库较小；将其提高到 debug，同时重现一个问题。

构建您自己的报告

如果您想自己生成报告（例如将其附加到您自己的崩溃中）记者，或添加您的应用程序版本），直接调用构建器：


import 'package:tracelet_doctor/tracelet_doctor.dart';
 
final report = await TraceletBugReport.build(
  appName: 'My App',
  appVersion: '2.4.1',   // e.g. from package_info_plus
  logLimit: 500,
  telematicsLimit: 100,
);
 
// Now copy, share, upload, or attach `report` however you like.

您还可以在任何配置映射上重复使用 secret-redaction 帮助器 - 方便如果您记录自己的配置：


final safe = TraceletBugReport.redactConfig(Tracelet.activeConfig.toMap());

报告内容（备忘单）

部分	来源	为什么它有帮助
健康检查	不翻译迟到	权限、OEM/电池、传感器、设备——常见的嫌疑点
警告	计算	“跟踪在后台停止”的可能原因
主动配置	NOTTRANS0LATE（已编辑）	确认实际有效的设置 - 包括任何应用的远程配置 (3.6.10+)
远程信息处理活动	不翻译迟到	最近的驾驶/碰撞事件 (3.3.0)
日志	不翻译迟到	SDK 功能的时间表，包括在后台

很高兴知道

隐私第一 — 报告完全在设备上生成。没有什么除非您发送，否则将被上传。秘密在包含之前会被编辑。
未初始化时工作 — 如果 Tracelet 尚未启动，Doctor 显示友好的“未初始化”屏幕而不是崩溃，并且每个报告部分优雅地降级。
在调试版本中交付 - 许多团队将 TraceletDoctor.show(context) 连接到摇动手势或隐藏的调试菜单，以便 QA 和支持人员可以在其中获取报告秒。