flutter_log_interceptor 0.1.0

The smart, zero-setup logging layer for Flutter. Beautiful colored logs, HTTP interception, in-app overlay, auto-silent in release — all from one line: FLog.init()

flutter_log_interceptor

The smart, zero-setup logging layer for Flutter.

Beautiful coloured terminal logs, HTTP interception, an in-app overlay with search and filter, and auto-silence in release — all from one line: FLog.init().

---

Features

• Zero-friction setup — one call in main(), nothing else required
• 8 log levels — debug, info, warn, error, fatal, http, nav, perf
• Two built-in themes — minimal (clean) and futuristic (rich badge backgrounds + dividers)
• Boxed terminal logs — wrap each record in ┌─/│/└─ box-drawing characters
• ANSI 256-colour output — distinct colour per level, JSON syntax highlighting
• HTTP interception — plug-in interceptor for Dio and a drop-in wrapper for dart:http
• In-app log overlay — scrollable panel with level filter, keyword search, and expandable tiles
• Floating debug button — draggable FAB that opens the overlay; shows a live record count badge
• Auto-silent in release — every log call is a no-op when kReleaseMode is true
• Structured JSON data — attach and render key/value maps on any log line
• FLogMixin — auto-tag logs with the enclosing class name
• Log history — in-memory buffer with JSON + plain-text export
• Auto-error capture — hooks FlutterError.onError
• Navigator observer — auto-logs every route change
• Performance timing — auto-logs frame render times via SchedulerBinding
• Live record count — FLog.recordCount ValueNotifier for reactive UIs

---

Getting started

Add to your pubspec.yaml:

dependencies:
  flutter_log_interceptor: ^0.1.0

If you use the in-app overlay with icons, ensure Material Icons are loaded:

# pubspec.yaml
flutter:
  uses-material-design: true

---

Usage

Minimal setup

void main() {
  FLog.init();
  runApp(MyApp());
}

Full setup

void main() {
  FLog.init(
    theme: FLogTheme.futuristic,
    minLevel: FLogLevel.debug,
    autoLogErrors: true,
    autoLogNavigation: true,
    autoLogPerformance: true,
    persistLogs: true,
    maxStoredLogs: 1000,
    boxedLogs: true,
    showFloatingButton: true,
  );
  runApp(MyApp());
}

---

Global log functions

logD('Button tapped');
logI('User logged in');
logW('Token expiring soon');
logE('Payment failed', error: e, st: stackTrace);
logF('Unhandled crash', error: e, st: stackTrace);

Tagged + structured logs

logD('Fetched 42 items', tag: 'ProductService');

FLog.i('Order placed', tag: 'OrderService', data: {
  'orderId': 'ORD_991',
  'amount': 2999,
  'success': true,
});

Mixin — auto-tag by class name

class ProductService with FLogMixin {
  void fetchProducts() {
    logD('Fetching products...'); // tag = "ProductService"
  }
}

---

In-app log overlay

Add FLogOverlay once inside your widget tree (it must sit inside the Navigator so that TextField can find its Overlay ancestor):

MaterialApp(
  home: Stack(
    children: [
      const MyHomePage(),
      FLogOverlay(),              // add once, near the root
    ],
  ),
);

Open and close it programmatically from anywhere:

FLogOverlay.show();
FLogOverlay.hide();

The overlay provides:

Feature	Detail
Level filter	Chips for ALL / DEBUG / INFO / WARN / ERROR / HTTP
Keyword search	Searches message, tag, error, data map, HTTP URL and body
Expandable tiles	Long messages, stack traces, and data maps expand inline
Copy all	Copies full log history to the clipboard
Clear	Wipes in-memory history
Auto-refresh	List updates in real time as new records arrive

Floating debug button

Enable a draggable FAB that opens the overlay and shows a live record count:

FLog.init(
  showFloatingButton: true,
  persistLogs: true,
);

Place FLogOverlay in the widget tree as shown above. The button is only rendered in debug mode and is completely absent in release builds.

---

Dio HTTP interception

final dio = Dio();
dio.interceptors.add(FLogDioInterceptor());

dart:http interception

final client = FLogHttpClient(http.Client());
final response = await client.get(Uri.parse('https://api.example.com/data'));

Navigation logging

MaterialApp(
  navigatorObservers: [FLog.navigatorObserver],
)

GoRouter navigation logging

GoRouter(
  observers: [FLogGoRouterObserver()],
  routes: [...],
)

GoRouter populates route names with full paths (e.g. /home, /profile/123). FLogGoRouterObserver reads those paths and logs every navigation event at the nav level. Framework-internal routes that don't start with / are skipped automatically.

---

Theme switching

// Clean, low-noise output
FLog.init(theme: FLogTheme.minimal);

// Rich output: badge backgrounds, ━━━ dividers, PERF icons
FLog.init(theme: FLogTheme.futuristic);

// Boxed — each record wrapped in ┌─/│/└─
FLog.init(boxedLogs: true);

// Custom — override only what you need
FLog.init(theme: FLogTheme(showTimestamp: false, maxBodyLength: 500));

Export logs

final json = FLog.exportAsJson();
final text = FLog.exportAsText();
FLog.clearHistory();

Reactive record count

ValueListenableBuilder<int>(
  valueListenable: FLog.recordCount,
  builder: (_, count, __) => Text('$count records'),
);

---

Output preview

minimal theme

  DEBUG  [AuthService] 10:32:01.204  Checking token validity
  INFO   [OrderService] 10:32:11.003  Order placed
  WARN   [TokenManager] 10:32:04.812  Access token expires in 4 min
  ERROR  [CartService] 10:32:09.553  Payment gateway timeout
             StackTrace:
               #0  CartService.checkout (cart_service.dart:88)

futuristic theme

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  █DEBUG█  [AuthService] 10:32:01.204  Checking token validity
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  █INFO █  [OrderService] 10:32:11.003  Order placed
────────────────────────────────────────────────────────────────────────────
               { "orderId": "ORD_991", "amount": 2999 }

boxedLogs: true

┌──────────────────────────────────────────────────────────────────────────
│   DEBUG  [AuthService] 10:32:01.204  Checking token validity
└──────────────────────────────────────────────────────────────────────────
┌──────────────────────────────────────────────────────────────────────────
│   INFO   [OrderService] 10:32:11.003  Order placed
└──────────────────────────────────────────────────────────────────────────

---

FLog.init() parameter reference

Parameter	Type	Default	Description
theme	FLogTheme	FLogTheme.minimal	Console output theme
minLevel	FLogLevel	FLogLevel.debug	Records below this level are ignored
autoLogErrors	bool	true	Hook FlutterError.onError
autoLogNavigation	bool	false	Log every route push/pop/replace
autoLogPerformance	bool	false	Log frame render times
persistLogs	bool	false	Keep records in memory for export/overlay
maxStoredLogs	int	500	Maximum records held in memory
boxedLogs	bool	false	Wrap each terminal record in ┌─/│/└─
showFloatingButton	bool	false	Show draggable FAB that opens the overlay

---

Comparison

Feature	flutter_log_interceptor	logger	talker	cr_logger
Zero-wrap setup	✅	✅	❌	❌
HTTP interception (Dio)	✅	❌	✅	✅
HTTP interception (http)	✅	❌	✅	✅
Structured JSON data	✅	❌	❌	❌
Two built-in themes	✅	❌	❌	❌
Boxed terminal logs	✅	❌	❌	❌
Mixin auto-tag	✅	❌	❌	❌
In-app overlay	✅	❌	✅	✅
Overlay keyword search	✅	❌	❌	❌
Floating debug button	✅	❌	❌	❌
Log export (JSON/text)	✅	❌	✅	✅
Auto-silent in release	✅	⚠️	⚠️	⚠️
Auto Flutter error capture	✅	❌	✅	❌
Auto nav logs	✅	❌	⚠️	❌
Performance timing	✅	❌	❌	❌
Reactive record count	✅	❌	❌	❌

---

Roadmap

See ROADMAP.md for the full plan.

• v0.2.0 — shake-to-open overlay, log persistence across hot restarts, share sheet
• v0.3.0 — VS Code extension + WebSocket log streaming

---

License

MIT