Flutter Debug Log

A lightweight, floating debug console for your Flutter apps.

Capture errors, monitor API requests, and view logs in a draggable floating window without leaving your app. Perfect for testing on physical devices or internal distribution builds.

Flutter Debug Log Screenshot

Features

  • 🚀 Zero Config Setup: Just 2 lines of code to get started.
  • 🪟 Floating Window: Draggable overlay that works over any screen.
  • 🌐 Network Logging: Built-in support for Dio interceptors.
  • 🐞 Global Error Handing: Automatically captures Flutter errors and uncaught exceptions.
  • 📱 Responsive: Works great on Phones and Tablets.

Installation

Add to your pubspec.yaml:

dependencies:
  flutter_debug_log: ^0.0.1

Quick Start

  1. Initialize in main():
void main() {
  FlutterDebugLog.init(); // <--- Add this
  runApp(const MyApp());
}
  1. Add the builder in MaterialApp:
return MaterialApp(
  title: 'My App',
  builder: FlutterDebugLog.builder, // <--- Add this
  home: MyHomePage(),
);

That's it! You will now see a floating bug icon in your app.

Usage

1. Initialization

Initialize the package in your main() function to enable global error handling:

void main() {
  FlutterDebugLog.init();
  runApp(const MyApp());
}

2. Overlay Integration

Add FlutterDebugLog.builder to your MaterialApp to inject the floating overlay:

return MaterialApp(
  // ...
  builder: FlutterDebugLog.builder,
  // ...
);

3. Network Logging (Dio)

To log network requests automatically, add the DebugLogInterceptor to your Dio instance:

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

Developer Guide

Manual Logging

You can log custom events using the DebugLogManager singleton. This is useful for tracking specific user actions or logic flows.

// Log simple info
DebugLogManager().log(
  type: LogType.info, 
  message: 'User tapped the checkout button',
);

// Log errors with stack traces
try {
  someRiskyOperation();
} catch (e, stack) {
  DebugLogManager().log(
    type: LogType.error,
    message: 'Operation failed',
    data: e.toString(),
    stackTrace: stack,
  );
}

Customizing the Overlay

If you using a custom navigation setup or want to restrict the overlay to specific screens, use the DebugOverlay widget directly instead of the global builder.

DebugOverlay(
  enable: kDebugMode, // Toggle visibility based on environment
  child: YourScreen(),
);

Accessing Logs Programmatically

(Coming Soon) - We plan to add an API to retrieve logs programmatically in future versions.

Example

Check out the example directory for a complete working application that demonstrates:

  • Global Error Handling
  • Network Request Logging
  • Manual Info/Error Logging
  • UI Integration

License

MIT

Libraries

flutter_debug_log