flutter_log_viewer 0.1.0

A compact, resizable in-app floating log viewer for Flutter applications.

flutter_log_viewer

中文文档

A lightweight in-app log viewer for Flutter. It keeps useful runtime logs close at hand, so developers, testers, and users can inspect, copy, or export them without leaving the current screen.

Features

• Floating Material panel with a translucent blurred background.
• Recording pause/resume independent from panel visibility.
• Automatic follow mode with an active toolbar indicator.
• Timestamped, severity-colored logs in a compact monospace layout.
• Tap one entry to highlight and copy it immediately.
• Long press with haptic feedback, then drag and edge-scroll to select multiple entries; release to copy the complete selection.
• Selection pauses automatic scrolling without pausing log recording.
• Drag the toolbar to move the panel and drag the lower-right handle to resize.
• Height is always limited to half of the available screen; width is limited to the viewport and a 720 logical-pixel reading width.
• Log count and selection/follow state in a fixed footer.
• Optional UTF-8 .log export handled by the app.
• Optional three-step guide shown once when the controller is initialized.
• No third-party runtime dependencies.

Preview

Requirements

• Dart >=3.11.5 <4.0.0
• Flutter >=3.29.0

These version requirements are declared in pubspec.yaml.

Setup

Create one controller and place LogViewerOverlay in MaterialApp.builder:

import 'package:flutter/material.dart';
import 'package:flutter_log_viewer/flutter_log_viewer.dart';

final logViewer = LogViewerController(
  label: 'My App Logs',
  recording: true,
  showPanel: true,
  showGuideOnInit: true,
  maxEntries: 1000,
  toast: (context, message) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(message)),
    );
  },
);

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      builder: (context, child) => LogViewerOverlay(
        controller: logViewer,
        child: child ?? const SizedBox.shrink(),
      ),
      home: const HomePage(),
    );
  }
}

Record logs from application code:

logViewer.verbose('Cache miss', tag: 'Storage');
logViewer.debug('Route changed to /profile', tag: 'Router');
logViewer.info('Profile saved', tag: 'Profile');
logViewer.warning('Request took 820ms', tag: 'Network');
logViewer.error(
  'Profile request failed',
  tag: 'Network',
  error: error,
  stackTrace: stackTrace,
);

flutter_log_viewer does not replace or intercept print, debugPrint, or a logging package. Forward logs from the logger already used by the app. This keeps release behavior explicit and avoids global side effects.

State Control

Panel visibility and recording are intentionally independent:

logViewer.hidePanel();        // Logs continue to be recorded.
logViewer.showPanel();
logViewer.togglePanel();

logViewer.setRecording(false); // New log calls are ignored.
logViewer.setRecording(true);
logViewer.clear();

Selecting a row only disables automatic scrolling. It does not change isRecording. Press the highlighted follow button to clear the selection, jump to the newest entry, and resume automatic scrolling.

Export

Exports use the conventional UTF-8 plain-text .log format. Each entry is one timestamped line, so the file opens in any text editor and works with standard log tools. The core package does not request storage permissions or choose a platform-specific file API. Provide export lifecycle callbacks in the host app:

final logViewer = LogViewerController(
  exportHandler: LogViewerExportHandler(
    exportStart: (context, controller) => showExportLoading(),
    exportEnd: (context, controller, file) async {
      hideExportLoading();
      // file.fileName: app-logs-20260716-143012.log
      // file.mimeType: text/plain
      // file.bytes: UTF-8 bytes
      await yourFileSaver.save(
        name: file.fileName,
        bytes: file.bytes,
        mimeType: file.mimeType,
      );
    },
  ),
);

The export toolbar action is disabled when no handler is supplied or the cache is empty. buildLogViewerExport(...) is public for app-owned export buttons.

Error Forwarding

Forward framework and zone errors if they should also appear in the viewer. Preserve the app's existing handlers when doing so:

final previousFlutterError = FlutterError.onError;
FlutterError.onError = (details) {
  logViewer.error(
    details.exceptionAsString(),
    tag: 'Flutter',
    stackTrace: details.stack,
  );
  previousFlutterError?.call(details);
};

Guide Behavior

showGuideOnInit defaults to false. Set it to true when this controller should open with the three-step guide. Once dismissed, the guide stays hidden for the rest of that controller's lifetime, including after the panel is hidden and opened again.

Example

The example app includes compact controls, simulated log levels, a live log stream, and working export paths. Desktop platforms use a save-location dialog, mobile platforms use the system file panel and then open the saved log, and web builds download the file.

cd example
flutter run