flutter_debug_overlay

Description:

flutter debug overlay

Flutter Debug Overlay #
The Flutter Debug Overlay package allows you to implement an overlay in your app for easy debugging,
even on devices away from any computer. It provides features like displaying logs in a sorted view,
inspecting logged HTTP requests with a JSON viewer, and supporting custom widgets for global actions
from anywhere in your app.
Features #

Global overlay: The debug overlay can be used as a global overlay even above your app
navigation.
Customizable triggers: By default, the debug overlay provides two triggers for opening the
overlay:

Mobile/Touch: Press and hold 2 fingers on the screen.
Desktop/Keyboard: Press ALT+F12.


Custom widgets: Supports custom widgets to enable global actions from everywhere in your app.
Log viewer: Displays your logs in a nice and sorted view.
HTTP request inspector: Allows you to inspect logged HTTP requests including a JSON viewer.
Provided HTTP middlewares: The debug overlay provides several middleware options for logging
HTTP
requests, including the DioLogInterceptor for the
popular dio package, HttpClientLogAdapter when utilizing the
default dart:io client, and HttpLogClient for
the http package.

Usage #
To use the debug overlay in your app, import the package and insert the DebugOverlay widget
at any point in your widget tree, to achieve a global overlay, put it in the builder of your
WidgetsApp.
The short and simple way (supports only limited features and customization):
import 'package:flutter_debug_overlay/flutter_debug_overlay.dart';

class MyApp extends StatelessWidget {
const MyApp({super.key});

@override
Widget build(BuildContext context) {
return MaterialApp(
builder: DebugOverlay.builder(),
home: const MyHomePage(),
);
}
}
copied to clipboard
The advanced way:
import 'package:flutter_debug_overlay/flutter_debug_overlay.dart';

class MyApp extends StatelessWidget {
static final LogBucket logBucket = LogBucket();
static final HttpBucket httpBucket = HttpBucket();

const MyApp({super.key});

@override
Widget build(BuildContext context) {
return MaterialApp(
builder: (context, child) {
return DebugOverlay(
hiddenFields: const [HttpHeaders.authorizationHeader, "Token"],
logBucket: logBucket,
httpBucket: httpBucket,
debugEntries: [ExampleDebug()],
child: child ?? const SizedBox.shrink(),
);
},
home: const MyHomePage(),
);
}
}
copied to clipboard
Open the Overlay #
By default, the debug overlay can be triggered either by pressing and holding two fingers on the
screen or by pressing ALT+F12 on a keyboard.
You can also use the visible property of the DebugOverlay widget to control it programmatically.
Add log entries #
To access your logs in the log view:

Create an instance of LogBucket.
Provide the instance to the DebugOverlay widget.
Add your logs to the bucket via add.

With this, all log events from your app will be displayed in the debug overlay.
Example Log Sources


Logger
import 'package:logger/logger.dart' hide LogEvent;

// Connects logger to the overlay.
Logger.addOutputListener((event) {
LogLevel? level = LogLevel.values
.firstWhereOrNull((element) => element.name == event.origin.level.name);
if (level == null) return;
MyApp.logBucket.add(LogEvent(
level: level,
message: event.origin.message,
error: event.origin.error,
stackTrace: event.origin.stackTrace,
time: event.origin.time,
));
});
copied to clipboard


Flutter Errors (e.g. Rendering Exceptions)
FlutterError.onError = (details) {
FlutterError.presentError(details);
MyApp.logBucket.add(LogEvent(
level: LogLevel.fatal,
message: details.exceptionAsString(),
error: (kDebugMode
? details.toDiagnosticsNode().toStringDeep()
: details.exception.toString()),
stackTrace: details.stack,
));
};
copied to clipboard


Uncaught Exceptions
PlatformDispatcher.instance.onError = (exception, stackTrace) {
MyApp.logBucket.add(LogEvent(
level: LogLevel.fatal,
message: "Unhandled Exception",
error: exception,
stackTrace: stackTrace,
));
return false; // "false" still dumps it to the console.
};
copied to clipboard


More information: https://docs.flutter.dev/testing/errors#handling-all-types-of-errors
Add HTTP requests #
To inspect HTTP requests:

Create an instance of HttpBucket.
Provide the instance to the DebugOverlay widget.
Add your requests to the bucket:


By using one of the provided middlewares

DioLogInterceptor for the dio package.
HttpClientLogAdapter when utilizing the default dart:io client.
and HttpLogClient for the http package.


Manually via add.

With this, all HTTP requests made within your app will be displayed and can be inspected in the
debug overlay.
Example HTTP Client Integrations


Dio
dio = Dio()..interceptors.add(DioLogInterceptor(MyApp.httpBucket));
copied to clipboard


HttpClient (dart:io)
httpClient = HttpClient();
httpClientAdapter = HttpClientLogAdapter(MyApp.httpBucket);
copied to clipboard

Log request
httpClientAdapter.onRequest(request);
copied to clipboard

Log response
httpClientAdapter.onResponse(request, response, responseBody);
copied to clipboard

Log error
httpClientAdapter.onError(request, error, stackTrace);
copied to clipboard




"http"
client = HttpLogClient(MyApp.httpBucket, http.Client());
copied to clipboard


Additional information #
If you have any questions or issues with the library, please don't hesitate to open an issue on
GitHub. Contributions are always welcome, so feel free to submit a pull request if you have any
improvements or bug fixes to share.
Acknowledgments #
Inspired by debug_overlay and
cr_logger.