feat: add message trace log for end-to-end delivery diagnostics

Matthias Nott

10 days ago 8d1f94e02e927fcb80d170fc85d13a091e5dc304

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
import 'package:flutter/foundation.dart';

/// A single trace entry capturing a message-handling event.
class TraceEntry {
  final DateTime timestamp;
  final String event;
  final String details;

  const TraceEntry({
    required this.timestamp,
    required this.event,
    required this.details,
  });

  @override
  String toString() =>
      '[${timestamp.toIso8601String().substring(11, 23)}] $event — $details';
}

/// Singleton ring-buffer trace service.
///
/// Captures message-handling events from MQTT, chat screen, and other
/// components. The buffer is capped at [maxEntries] (default 200).
/// Works in both debug and release builds.
class TraceService {
  TraceService._();
  static final TraceService instance = TraceService._();

  static const int maxEntries = 200;
  final List<TraceEntry> _entries = [];

  /// All entries, oldest first.
  List<TraceEntry> get entries => List.unmodifiable(_entries);

  /// Add a trace entry. Oldest entry is evicted once the buffer is full.
  void addTrace(String event, String details) {
    _entries.add(TraceEntry(
      timestamp: DateTime.now(),
      event: event,
      details: details,
    ));
    if (_entries.length > maxEntries) {
      _entries.removeAt(0);
    }
    debugPrint('[TRACE] $event — $details');
  }

  /// Clear all entries.
  void clear() => _entries.clear();
}