診断、ログ、バグレポート

すべての Tracelet アプリは、SDK がデバイス上で行っていること (権限、権限など) を記録します。追跡状態、センサーの可用性、ローリングログ。の tracelet_doctor パッケージは、そのすべてを ワンタップの診断画面とコピーアンドペーストのバグレポートがあるため、何かが間違っているようです。あなた (またはユーザー) は、何が起こったのかを正確に把握できます。

3.3.0 の新機能: Doctor の コピー ボタンに すべて がバンドルされるようになりました (ヘルス + 構成 + ログ + テレマティクス) を単一の Markdown レポートにまとめ、新しい共有ボタンを使用すると、.md ファイルとしてダウンロードしたり電子メールで送信したりできます。もありますログビューアの ログをコピー ボタン。

30秒バージョン

tracelet_doctor を dev 依存関係 (通常のものではありません) として追加します - これはデバッグです 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
{ "地理": { "距離フィルター": 10.0, ... },
"http": { "url": "«編集済み»", "ヘッダー": "«編集済み»", ... } }
```
 
## 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 timestamp。ログはデバイス上の 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/バッテリー、センサー、デバイス — よくある容疑者
警告	計算された	「追跡がバックグラウンドで停止する」可能性のある原因
アクティブな構成	`Tracelet.activeConfig` (編集済み)	適用された remote config (3.6.10+) を含む、実際に有効な設定を確認します。
テレマティクスイベント	非トランスレート	最近の運転/衝撃イベント (3.3.0)
ログ	非トランスレート	バックグラウンドを含む SDK の動作のタイムライン

知っておいてよかった

プライバシーを第一に — レポートは 完全にデバイス上で生成されます。何もない あなたが送信しない限り、アップロードされます。シークレットは組み込まれる前に編集されます。
初期化されていない場合でも機能します — Tracelet がまだ開始されていない場合、Doctor クラッシュする代わりにフレンドリーな「初期化されていません」画面が表示され、各レポートが表示されます。セクションは正常に劣化します。
デバッグビルドで出荷 — 多くのチームは TraceletDoctor.show(context) を QA とサポートがレポートを取得できるように、シェイクジェスチャーまたは非表示のデバッグメニューを使用します。秒。