Diagnósticos, registros e informes de errores

Cada aplicación Tracelet registra lo que hace el SDK en el dispositivo: permisos, estado de seguimiento, disponibilidad de sensores y un registro continuo. El El paquete tracelet_doctor convierte todo eso en un pantalla de diagnóstico de un toque y un informe de error de copiar y pegar, para que cuando algo parece mal, usted (o sus usuarios) pueden capturar exactamente lo que sucedió.

La versión de 30 segundos

Agregue tracelet_doctor como dependencia de desarrollo (no normal): es una depuración herramienta, y Flutter excluye los paquetes de dependencia de desarrollo de las versiones de lanzamiento:

flutter pub add dev:tracelet_doctor

Luego proteja el uso detrás de kDebugMode para que quede eliminado de las versiones de lanzamiento:

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

Eso abre una hoja con:

• Advertencias: cualquier cosa que pueda afectar el seguimiento (permiso denegado, ahorro de energía). modo, OEM agresivo, sin sensor de movimiento significativo, ubicaciones simuladas…).
• Permisos, estado de seguimiento, batería y OEM, configuración, sensores, base de datos.
• Un botón Ver registros (las últimas 500 líneas de registro).
• Botones Copiar informe de error y Compartir informe de error en la parte superior derecha.

Presentar un informe de error (para sus usuarios)

Cuando un usuario informa un problema, la forma más rápida de ayudarlo es obtener un Tracelet informe de error. Diles que:

1. Abra la pantalla Tracelet Doctor (dondequiera que la haya colocado en su aplicación).
2. Toca el ícono Compartir (↗) — o Copiar (⧉) — en la parte superior derecha.
3. Péguelo/adjunte en su canal de soporte o en el problema de GitHub, junto con cualquiera de sus propios registros de aplicaciones.

El informe es Markdown simple y se ve así:

# 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": { "distanciaFilter": 10.0, ... },
"http": { "url": "«redactado»", "headers": "«redactado»", ... } }
```
 
## 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
...

Trabajar con registros directamente

El Doctor lee los mismos registros a los que puede acceder desde la API. Esto es útil si desea crear su propia pantalla de diagnóstico o enviar registros a su backend.

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

Cada LogEntry tiene id, level (DEBUG/INFO/WARN/ERROR), message, y un ISO-8601 timestamp. Los registros se almacenan en la base de datos SQLite del dispositivo, por lo que sobreviven a los reinicios de la aplicación y capturan la actividad en segundo plano, exactamente lo mismo. eventos que de otro modo serían imposibles de ver en un depurador.

Creando tu propio informe

Si prefiere generar el informe usted mismo (por ejemplo, adjuntarlo a su propio informe de fallos) reporter, o agregue la versión de su aplicación), llame al creador directamente:

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.

También puedes reutilizar solo el asistente redacción secreta en cualquier mapa de configuración: útil si registra su propia configuración:

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

¿Qué hay en el informe (hoja de referencia)?

Es bueno saberlo

• Privacidad primero: el informe se genera completamente en el dispositivo. Nada se carga a menos que tú lo envíes. Los secretos se redactan antes de incluirlos.
• Funciona cuando no está inicializado — si Tracelet aún no se ha iniciado, el Doctor muestra una pantalla amigable “no inicializada” en lugar de fallar, y cada informe La sección se degrada con gracia.
• Envíelo en versiones de depuración: muchos equipos conectan TraceletDoctor.show(context) a un Agite el gesto o un menú de depuración oculto para que el control de calidad y el soporte puedan obtener un informe en artículos de segunda clase.