Flutter package for implementing a debug overlay in your app, providing features like log viewers, HTTP request inspectors, and customizable widgets for easy debugging.
MIT License
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.
DioLogInterceptor
for thedio
package, HttpClientLogAdapter
when utilizing thedart:io
client, and HttpLogClient
forhttp
package.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(),
);
}
}
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(),
);
}
}
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.
To access your logs in the log view:
LogBucket
.DebugOverlay
widget.add
.With this, all log events from your app will be displayed in the debug overlay.
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,
));
});
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,
));
};
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.
};
More information: https://docs.flutter.dev/testing/errors#handling-all-types-of-errors
To inspect HTTP requests:
HttpBucket
.DebugOverlay
widget.DioLogInterceptor
for the dio
package.HttpClientLogAdapter
when utilizing the default dart:io
client.HttpLogClient
for the http
package.add
.With this, all HTTP requests made within your app will be displayed and can be inspected in the debug overlay.
Dio
dio = Dio()..interceptors.add(DioLogInterceptor(MyApp.httpBucket));
HttpClient (dart:io
)
httpClient = HttpClient();
httpClientAdapter = HttpClientLogAdapter(MyApp.httpBucket);
httpClientAdapter.onRequest(request);
httpClientAdapter.onResponse(request, response, responseBody);
httpClientAdapter.onError(request, error, stackTrace);
"http"
client = HttpLogClient(MyApp.httpBucket, http.Client());
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.
Inspired by debug_overlay and cr_logger.