Snapshot do README original do repositório-fonte vinculado. Consulte o repositório para o conteúdo mais recente.
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.
- Supports implementing custom request/response body widgets using
DebugHttpHandler.
- 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(),
);
}
}
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(),
);
}
}
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;
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;
};
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));
-
HttpClient (dart:io)
httpClient = HttpClient();
httpClientAdapter = HttpClientLogAdapter(MyApp.httpBucket);
- Log request
httpClientAdapter.onRequest(request);
- Log response
httpClientAdapter.onResponse(request, response, responseBody);
- Log error
httpClientAdapter.onError(request, error, stackTrace);
-
"http"
client = HttpLogClient(MyApp.httpBucket, http.Client());
Example custom body widgets
DebugOverlay.httpHandler = CustomHttpHandler();
class CustomHttpHandler extends DebugHttpHandler {
@override
BodyType determineBodyType(headers, body) {
var mediaType = headers != null ? extractMediaType(headers) : null;
if (mediaType?.type == "image") {
return BodyType.custom;
}
return super.determineBodyType(headers, body);
}
@override
Widget buildCustomBody(context, headers, body, hiddenKeys) {
if (body is List<int>) {
return Image.memory(Uint8List.fromList(body));
}
return Text(body.toString());
}
}
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.