Диагностика, журналы и отчеты об ошибках

Каждое приложение Tracelet записывает, что SDK делает на устройстве — разрешения, состояние отслеживания, доступность датчиков и скользящий журнал. Пакет tracelet_doctor превращает все это в экран диагностики одним касанием и отчет об ошибке, который можно копировать и вставлять, поэтому при что-то выглядит не так, вы (или ваши пользователи) можете точно зафиксировать, что произошло.

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. отчет об ошибке. Скажите им:

1. Откройте экран Tracelet Doctor (где бы вы его ни разместили в приложении).
2. Нажмите значок Поделиться (↗) или Копировать (⧉) — в правом верхнем углу.
3. Вставьте/прикрепите его в свой канал поддержки или в выпуск 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
...

Работа с логами напрямую

Доктор читает те же журналы, к которым вы можете получить доступ через 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 на устройстве, поэтому они выдерживают перезапуск приложения и фиксируют фоновую активность — именно события, которые иначе невозможно увидеть в отладчике.

Создание собственного отчета

Если вы предпочитаете создать отчет самостоятельно (например, прикрепить его к своему собственному сбою reporter или добавьте свою версию приложения), позвоните сборщику напрямую:

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());

Что в отчете (шпаргалка)

Приятно знать

• Конфиденциальность прежде всего — отчет создается полностью на устройстве. Ничего загружается, если только вы его не отправите. Секреты редактируются перед включением.
• Работает без инициализации — если Tracelet еще не запущен, Доктор показывает дружелюбный «не инициализированный» экран вместо сбоя, и каждый отчет раздел изящно деградирует.
• Добавляйте его в отладочных сборках — многие команды подключают TraceletDoctor.show(context) к жест встряхивания или скрытое меню отладки, чтобы отдел контроля качества и служба поддержки могли получить отчет в секунды.