Flutter Super Log Manager

❓ Why Use This?

Flutter Super Log Manager is designed to bridge the gap between development logs and on-device testing.

💡 When to use

• QA & Testing: Allow testers to see application logs and errors instantly without connecting to a computer.
• Complex Flows: Debug multi-step user flows (like authentication or payments) where checking the console is difficult.
• Field Debugging: Diagnose issues on physical devices in real-world scenarios.
• Silent Error Monitoring: Keep track of exceptions in the background without disturbing the user.
• Startup Events: Debug issues when opening the app via notifications or deep links.

✨ Key Benefits

• 🔌 Plug & Play: Works immediately with zero configuration.
• 📱 Device Independent: View logs on any device, anywhere.
• 🔍 Powerful Search: Find exactly what you're looking for with regex-capable search and filtering.
• ⚡ Zero Overhead: Completely compiles out or disables in production builds for maximum performance.

📋 Table of Contents

• ✨ Features
• 🚀 Quick Start
• 📖 Usage Examples
• 🎯 API Reference
• 🎨 Customization
• 🔧 Integration Examples
• 🚦 Production Usage
• 🐛 Troubleshooting
• 📝 Changelog
• 📄 License

🚀 Quick Start

1. Add dependency

   dependencies:
     flutter_super_log_manager: ^1.0.0
   

2. Initialize in main.dart

   import 'package:flutter_super_log_manager/flutter_super_log_manager.dart';
   
   void main() {
     // Wrap your app with SuperLogManager.runApp
     SuperLogManager.runApp(
       const MyApp(),
       config: const SuperLogConfig(
         enabled: true,
         showOverlayBubble: true,
       ),
     );
   }
   

📖 Usage Examples

Minimal Usage

Easily toggle the logger for production builds using a constant or environment variable:

import 'package:flutter_super_log_manager/flutter_super_log_manager.dart';


void main() {
  SuperLogManager.runApp(
    const MyApp(),
  );
}

Ready-made Configurations

We provide several named constructors for common use cases:

1. Development (Default)

Use this constructor to enable all features for debugging:

config: const SuperLogConfig.development()

• Enabled: Yes
• Overlay: Visible
• Features: All enabled (print capture, debugging, etc.)
• Use case: Day-to-day development and debugging.

2. Production

Use this constructor to completely disable the logger for release builds:

config: const SuperLogConfig.production()

• Enabled: No
• Overlay: Hidden
• Features: None. The logger is completely disabled and bypasses all logic.
• Use case: Release builds where you want zero overhead.

3. Error Tracking

Use this constructor to capture errors silently without the UI overlay:

config: const SuperLogConfig.errorTracking()

• Enabled: Yes (Background only)

• Overlay: Hidden

• Features: Captures only errors and exceptions. Print capturing is disabled to reduce noise.

• Use case: "Silent" monitoring. Errors are caught and stored in memory (up to 500), which you can programmatically access or export if needed, without showing the UI to the user.

  How to access logs programmatically:

  // Get all logs
  final logs = SuperLogManager.instance.logs;
    
  // Get error count
  final errorCount = SuperLogManager.instance.errorCount;
    
  // Export logs manually
  if (errorCount > 0) {
    final errorLogs = logs.where((l) => l.level == LogLevel.error).toList();
    // ... send to your server
  }
  

Comprehensive Configuration

Here is an example showing all available configuration options:

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

void main() {
  SuperLogManager.runApp(
    const MyApp(),
    config: const SuperLogConfig(
      // 🛠️ Core Settings
      enabled: true,              // Master switch for the logger
      maxLogs: 2000,              // Maximum logs to keep in memory
      
      // 🫧 Bubble Appearance
      showOverlayBubble: true,    // Show the floating debug bubble
      bubbleSize: 56.0,           // Size of the bubble
      bubbleColor: Colors.blue,   // Background color of the bubble
      bubbleIconColor: Colors.white, // Color of the bug icon
      initialBubblePosition: Offset(16, 100), // Start position
      enableBubbleDrag: true,     // Allow user to drag the bubble
      hideBubbleWhenScreenOpen: true, // Hide bubble when log screen is open
      enableLongBubbleClickExport: true, // Long press bubble to export logs
      
      // 🚨 Error Badge
      errorBadgeColor: Colors.red,     // Color of the error count badge
      errorBadgeTextColor: Colors.white, // Color of the badge text
      
      // ⚙️ Behavior
      autoDetectErrorLevel: true, // Auto-mark logs with "error" as Error level
      captureDebugPrint: true,    // Capture debugPrint() calls
      capturePrint: true,         // Capture print() calls
      mirrorLogsToConsole: true,  // Also print logs to system console
      
      // 📱 Log Screen UI
      panelHeightFraction: 0.9,   // Height of log screen (0.0 - 1.0)
      dimOverlayBackground: true, // Dim background when screen is open
      
      // ⚡ Features
      enableLogFiltering: true,   // Allow filtering by level
      enableLogSearch: true,      // Allow text search
      enableLogDeletion: true,    // Allow deleting logs
      enableLogExport: true,      // Allow copying logs to clipboard
    ),
  );
}

Advanced Initialization (preRun & postRun)

For complex apps, you often need to initialize services (like Firebase, Hive, or Supabase) before the app starts. SuperLogManager.runApp provides preRun and postRun callbacks for this purpose.

Why use preRun?

• It runs inside the error-catching zone, so any initialization errors are captured by the logger.
• It awaits your async code, ensuring everything is ready before runApp is called.
• If it returns false, the app startup is aborted (useful for critical failures).

Why use postRun?

• It runs after the app widget is mounted.
• Perfect for logging "App Started" events or triggering initial navigation.

void main() {
  SuperLogManager.runApp(
    const MyApp(),
    // 1️⃣ Run async initialization code safely
    preRun: () async {
      try {
        // Initialize your services here
        await Firebase.initializeApp();
        await Hive.initFlutter();
        
        // Log success
        SuperLogManager.instance.addLog('Services initialized successfully');
        return true; // Continue startup
      } catch (e) {
        // 🚨 This error will be captured by SuperLogManager!
        throw 'Critical initialization failure: $e';
      }
    },
    // 2️⃣ Run code after the app is mounted
    postRun: () {
      SuperLogManager.instance.addLog('App is running!');
    },
  );
}

🎯 API Reference

SuperLogConfig

Field	Type	Default	Description
enabled	bool	true	Master switch. If false, the logger does nothing.
maxLogs	int	1000	Maximum number of logs to keep in memory.
showOverlayBubble	bool	true	Whether to show the floating debug bubble.
bubbleSize	double	56.0	Diameter of the floating bubble.
bubbleColor	Color	Colors.blue	Background color of the bubble.
bubbleIconColor	Color	Colors.white	Color of the bug icon inside the bubble.
initialBubblePosition	Offset	Offset(16, 200)	Starting position of the bubble.
enableBubbleDrag	bool	true	Allow dragging the bubble around the screen.
hideBubbleWhenScreenOpen	bool	true	Hide bubble when the log screen is active.
enableLongBubbleClickExport	bool	true	Long press bubble to copy all logs.
errorBadgeColor	Color	Colors.red	Background color of the error count badge.
errorBadgeTextColor	Color	Colors.white	Text color of the error count badge.
autoDetectErrorLevel	bool	true	Auto-detect "error" keywords in logs.
captureDebugPrint	bool	true	Intercept debugPrint() calls.
capturePrint	bool	true	Intercept print() calls.
mirrorLogsToConsole	bool	true	Print captured logs to the system console.
panelHeightFraction	double	0.85	Height of the log screen (0.0 to 1.0).
dimOverlayBackground	bool	true	Dim the background when log screen is open.
enableLogFiltering	bool	true	Enable UI for filtering logs by level.
enableLogSearch	bool	true	Enable UI for searching logs.
enableLogDeletion	bool	true	Enable UI for deleting logs.
enableLogExport	bool	true	Enable UI for exporting logs.

✨ Features

• 🚀 Automatic Error Catching: Automatically captures Flutter framework errors and Dart exceptions.
• 🎯 Draggable Overlay: Always-on-top debug bubble to access logs from anywhere.
• 📱 In-App Console: Full-featured log viewer with search, filtering, and selection.
• ⚡ Performance Optimized: Efficient log filtering and rendering, suitable for production use (when disabled).
• 🔍 Smart Filtering: Filter logs by level (Info, Warning, Error) or search text instantly.
• 📋 Clipboard Support: Copy logs to clipboard for easy sharing.
• 🎨 Fully Customizable: Customize colors, sizes, and behavior via SuperLogConfig.
• 🔌 Print Capture: Automatically captures print() and debugPrint() calls.

📱 Example App

Try the plugin with our comprehensive example app:

# Clone the repository
git clone https://github.com/a7mdragab1/flutter_super_log_manager.git
cd flutter_super_log_manager

# Run the example
cd example
flutter run

The example demonstrates:

• ✅ Basic setup with debug bubble
• ✅ Advanced configuration
• ✅ Error simulation and logging
• ✅ Manual log addition
• ✅ Print capture functionality

📊 Benchmarks

Performance benchmarks on various devices:

Operation	Time	Memory Impact
Add 1000 logs	< 50ms	~2MB
Search 5000 logs	< 10ms	Minimal
Filter by level	< 5ms	Minimal
Clear all logs	< 20ms	Full recovery

Benchmarks performed on mid-range Android device

📝 Changelog

1.0.0 - Initial Release

• 🚀 Complete debug logging system with automatic error catching
• 🎯 Draggable overlay bubble with RTL/LTR support
• 📱 Advanced log viewer with search, filtering, and selection
• 🎨 Extensive customization options and theming
• ⚡ Performance optimizations with batch processing
• 🌍 Internationalization support (RTL/LTR)
• 📦 Pure Dart implementation - works on all platforms
• 🔧 Easy production disable with zero overhead
• 📚 Comprehensive documentation and examples

🏆 Contributing

We welcome contributions! Here's how you can help:

Ways to Contribute

• 🐛 Report Bugs: Open issues for bugs you find
• 💡 Suggest Features: Share your ideas for improvements
• 📝 Improve Documentation: Help make docs clearer
• 🧪 Write Tests: Add test cases for better reliability
• 💻 Submit Code: Fix bugs or add features

Development Setup

Follow these steps to set up the project for development:

# Fork and clone the repository
git clone https://github.com/a7mdragab1/flutter_super_log_manager.git
cd flutter_super_log_manager

# Install dependencies
flutter pub get

# Run tests
flutter test

# Run example app
cd example && flutter run

Pull Request Process

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📞 Support & Community

Getting Help

• 📖 Documentation: Check this README and inline code documentation
• 🐛 Bug Reports: Open an issue
• 💬 Discussions: Use GitHub Discussions for questions
• 📧 Email: Contact maintainers for sensitive issues

Resources

• 🎯 Example App: Complete working example
• 📚 API Reference: Detailed API documentation
• 🔧 Troubleshooting: Common issues and solutions

📄 License

This project is licensed under the MIT License - see the LICENSE file for details:

MIT License

Copyright (c) 2025 Flutter Super Log Manager

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---