Flutter Awesome Logger 🚀

Lightweight debugging with floating logger, automatic API logging (using interceptor), Flutter general logging, and a beautiful UI for viewing logs

📖 Documentation • 🚀 Installation • 💡 Examples • 🎨 Customization

🖼️ App Screenshots Gallery

📦 Add to your pubspec.yaml

🔄 Install the package

📱 Import in your Dart code

⚡ Easiest Setup (Just 2 Lines!)

The absolute simplest way to get started - just wrap your app:

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

// Global navigator key for navigation (required for logger history page)
final navigatorKey = GlobalKey<NavigatorState>();

void main() {
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return FlutterAwesomeLogger(
      navigatorKey: navigatorKey, // Required if logger history page does not open on floating button press
      child: MaterialApp(
        navigatorKey: navigatorKey,
        home: const YourHomePage(),
      ),
    );
  }
}

That's it! 🎉 The logger is now active with default settings. You'll see:

• 📱 Floating logger button on your screen
• 📊 Unified logger interface ready for all your logs

🚀 API Demo Page (Advanced Example)

For a comprehensive demonstration of API logging capabilities, check out our example app's dedicated API demo page:

// Navigate to API demo page from your app
Navigator.push(
  context,
  MaterialPageRoute(builder: (context) => const ApiDemoPage()),
);

What the API demo includes:

• ✅ GET Requests - Fetch all users and individual users by ID
• ✅ POST Requests - Create new users with sample data
• ✅ Error Handling - Simulate and handle API errors (404, network issues)
• ✅ Loading States - Beautiful loading indicators during requests
• ✅ User Cards - Attractive display of user data with avatars and details
• ✅ Auto-logging - Every request is automatically logged with full details
• ✅ cURL Generation - Copy-paste ready cURL commands for testing

Features demonstrated:

• Real-time API logging with Dio interceptor
• Error state management and user feedback
• Professional UI with loading states and error displays
• Comprehensive user data model with JSON parsing
• Multiple HTTP methods (GET, POST) with proper error handling

📋 How to Get Logs in the Unified Interface

🌐 API Logs

For HTTP requests and responses

To capture API logs in the unified logger interface, add the Dio interceptor:

Step 1: Add the interceptor to your Dio instance

import 'package:dio/dio.dart';
import 'package:flutter_awesome_logger/flutter_awesome_logger.dart';

final dio = Dio();
dio.interceptors.add(FlutterAwesomeLoggerDioInterceptor());

// Now all API calls are automatically logged!
final response = await dio.get('https://jsonplaceholder.typicode.com/users');

What you get:

• ✅ Automatic capture - All requests and responses logged automatically
• ✅ cURL generation - Copy-paste ready cURL commands for testing
• ✅ Error handling - Network errors and HTTP errors captured
• ✅ Performance timing - Request duration tracking
• ✅ Advanced filtering - Filter by status code, method, or endpoint
• ✅ Search functionality - Search through URLs, headers, and response content

📊 General Logs

For application logs and debugging

To capture general logs in the unified logger interface:

Step 1: Create a logger instance

Create a my_logger.dart file (or any name you prefer):

// my_logger.dart
import 'package:flutter_awesome_logger/flutter_awesome_logger.dart';

/// Global logger instance for use throughout the app.
/// Use this in files where you DON'T use AwesomeLoggerMixin.
final logger = FlutterAwesomeLogger.loggingUsingLogger;

Step 2: Use the logger throughout your app

import 'my_logger.dart';

class MyService {
  void performOperation() {
    // Debug information (development only)
    logger.d('Starting complex operation with parameters: $params');
    
    // General information (important events)
    logger.i('User logged in successfully');
    
    // Warnings (potential issues)
    logger.w('API rate limit approaching: ${remaining} requests left');
    
    // Errors (with full context)
    try {
      // Your code here
    } catch (e, stackTrace) {
      logger.e('Failed to process user data', error: e, stackTrace: stackTrace);
    }
  }
}

What you get:

• ✅ Multiple log levels - DEBUG (grey), INFO (blue), WARNING (orange), ERROR (red)
• ✅ Stack trace support - Full error context with file paths and line numbers
• ✅ Source File Tracking - 🔍 Easy Debugging: See exact file paths and line numbers for instant issue identification - no more guessing where your code is logging from!
• ✅ Advanced filtering - Filter by log level, source file, or search content
• ✅ Export capabilities - Copy individual logs or export entire filtered sets
• ✅ Real-time updates - Logs appear instantly as your app runs

⚠️ Release Build Limitations

🔍 File Paths in Production/Release Builds

In debug mode, the logger automatically extracts file paths from stack traces to show you exactly where each log originates. However, in release/production builds, Flutter strips debug information (including stack traces) for performance and security reasons.

What you'll see:

• Debug mode: ./lib/pages/home_page.dart:42:10 ✅
• Release mode: unknown ⚠️

💡 Solution: Use the source Parameter

To maintain source tracking in release builds, use the optional source parameter:

// Without source (works in debug, shows 'unknown' in release)
logger.d('Loading user data');

// With source (works in both debug AND release builds!)
logger.d('Loading user data', source: 'HomeScreen');
logger.i('User logged in successfully', source: 'AuthService');
logger.w('Cache miss detected', source: 'CacheManager');
logger.e('Failed to fetch data', error: e, source: 'ApiRepository');

🎯 Best Practice for Production Apps

Option 1: Using AwesomeLoggerMixin (Recommended)

import 'package:flutter_awesome_logger/flutter_awesome_logger.dart';

class UserRepository with AwesomeLoggerMixin {
  // logger.d(), logger.i(), etc. automatically use 'UserRepository' as source!
  
  Future<User> fetchUser(String id) async {
    logger.d('Fetching user: $id'); // source: 'UserRepository'
    try {
      final user = await api.getUser(id);
      logger.i('User fetched successfully'); // source: 'UserRepository'
      return user;
    } catch (e, stack) {
      logger.e('Failed to fetch user', error: e, stackTrace: stack); // source: 'UserRepository'
      rethrow;
    }
  }
}

Option 2: Using Scoped Logger

class UserRepository {
  final _logger = logger.scoped('UserRepository');
  // Or: late final _logger = logger.scoped(runtimeType.toString());
  
  Future<User> fetchUser(String id) async {
    _logger.d('Fetching user: $id'); // source: 'UserRepository'
    // ...
  }
}

Option 3: Manual source parameter

class UserRepository {
  static const _source = 'UserRepository'; // Define once per class
  
  Future<User> fetchUser(String id) async {
    logger.d('Fetching user: $id', source: _source);
    try {
      final user = await api.getUser(id);
      logger.i('User fetched successfully', source: _source);
      return user;
    } catch (e, stack) {
      logger.e('Failed to fetch user', error: e, stackTrace: stack, source: _source);
      rethrow;
    }
  }
}

🏷️ Impact on Class Filtering

When file paths show as unknown in release builds:

• Classes button will appear grey (no classes available)
• Class filtering won't work since classes are extracted from file paths

Solution: Always use the source parameter in production apps to enable full filtering capabilities!

🏷️ AwesomeLoggerMixin & Scoped Logger

🎯 Automatic Source Tracking for Classes

The easiest way to add class-based source tracking to all your logs. No more manually passing source to every log call!

🔧 Option 1: AwesomeLoggerMixin (Recommended)

Simply add the mixin to your class - all logs will automatically use the class name as source:

import 'package:flutter_awesome_logger/flutter_awesome_logger.dart';

// Works with Cubits, Blocs, Services, Repositories, Widgets - any class!
class CubitAppConfig extends Cubit<StateAppConfig> with AwesomeLoggerMixin {
  CubitAppConfig() : super(const StateAppConfig()) {
    logger.d('Instance created, hashCode: $hashCode'); 
    // ↑ Logs with source: 'CubitAppConfig' automatically!
  }

  void loadConfig() {
    logger.i('Loading config...');  // source: 'CubitAppConfig'
    logger.w('Cache expired');      // source: 'CubitAppConfig'
  }
  
  void handleError(Object error, StackTrace stack) {
    logger.e('Failed to load', error: error, stackTrace: stack); 
    // ↑ source: 'CubitAppConfig'
  }
}

How it works:

• The mixin provides a logger getter that returns a ScopedLogger
• Uses runtimeType.toString() to automatically get the class name
• The mixin's logger shadows any imported global logger within the class
• Works correctly with inheritance - subclasses get their own class name

🔧 Option 2: Scoped Logger

For more control, create a scoped logger instance:

import 'package:flutter_awesome_logger/flutter_awesome_logger.dart';

class MyService {
  // Option A: Hardcoded source name
  final _logger = logger.scoped('MyService');
  
  // Option B: Using runtimeType (use late final)
  // late final _logger = logger.scoped(runtimeType.toString());
  
  void doSomething() {
    _logger.d('Doing something'); // source: 'MyService'
    _logger.i('Task completed');  // source: 'MyService'
  }
}

📊 Comparison Table

💡 Tips

• No Import Conflicts: Don't import my_logger.dart in files where you use AwesomeLoggerMixin. The mixin provides its own logger getter.
• Use logger.source: Access the source name with logger.source (returns the class name)
• Production Ready: Uses runtimeType which is available in both debug and release builds
• Filtering: All logs with source are filterable in the logger UI using the Classes filter

📝 Import Guide

🏷️ Class-Based Filtering

🎯 Focus on Specific App Components

Class filtering helps you narrow down logs to specific parts of your application by filtering based on class names extracted from file paths.

🖱️ How to Use Class Filtering

1. Open Logger History: Tap the floating logger button to access the unified logger interface
2. Click Classes Button: Look for the "Classes" button in the filter section (appears purple when classes are available, grey when none exist)
3. Select Classes: Choose from available class names in the bottom sheet
4. View Toggle: Switch between list view and compact chip view using the toggle button
5. Search Classes: Use the search field to quickly find specific classes
6. Apply Filters: Selected classes will be highlighted and logs filtered accordingly

🎨 Visual Indicators

• Purple Button: Classes are available for filtering
• Grey Button: No classes found in current logs (still clickable to learn about the feature)
• Selected Classes: Purple background with white text and count badges
• Compact View: Space-efficient chip layout for quick selection

💡 What Classes Are Available?

• Automatic Detection: Classes are extracted from general log file paths
• File-Based: Class names come from .dart file names (e.g., home_page.dart → home_page)
• Real-time Updates: Available classes update as you use different parts of your app
• Smart Filtering: Only shows classes that have generated logs

🔍 Advanced Class Filtering

// Programmatic access to class filtering
final availableClasses = FlutterAwesomeLogger.getAvailableClasses();
final classCounts = FlutterAwesomeLogger.getClassCounts();

// Classes are automatically extracted from logs like:
logger.d('User tapped login button'); // Creates 'my_widget' class filter

🔧 Configuration Options

🎛️ FlutterAwesomeLogger Configuration

enabled: true

enabled: false

enabled: someFuture()

📊 AwesomeLoggerConfig

const AwesomeLoggerConfig({
  int maxLogEntries = 1000,
  bool showFilePaths = true,
  bool showEmojis = true,
  bool useColors = true,
  int stackTraceLines = 0,
  bool enableCircularBuffer = true,
});

🎨 FloatingLoggerConfig

const FloatingLoggerConfig({
  Color backgroundColor = Colors.deepPurple,
  IconData icon = Icons.developer_mode,
  bool showCount = true,
  bool enableGestures = true,
  bool autoSnapToEdges = true,
  double size = 60.0,
});

📚 Advanced Usage

Accessing Log History

// Get all stored logs
final logs = FlutterAwesomeLogger.getLogs();

// Get logs by level
final errorLogs = FlutterAwesomeLogger.getLogsByLevel('ERROR');

// Get recent logs
final recentLogs = FlutterAwesomeLogger.getRecentLogs(
  duration: Duration(minutes: 10),
);

// Clear all logs
FlutterAwesomeLogger.clearLogs();

// Export logs as formatted text
String exportedLogs = FlutterAwesomeLogger.exportLogs();

Programmatically Show Logger UI

// Show the unified logger history page
Navigator.push(
  context,
  MaterialPageRoute(
    builder: (context) => const AwesomeLoggerHistoryPage(),
  ),
);

Pause/Resume Logging

// Pause all logging (both console and storage)
FlutterAwesomeLogger.setPauseLogging(true);

// Resume logging
FlutterAwesomeLogger.setPauseLogging(false);

// Check if logging is paused
bool isPaused = FlutterAwesomeLogger.isPaused;

Control Floating Logger Visibility

// Check if floating logger is visible
bool isVisible = FlutterAwesomeLogger.isVisible();

// Show/hide the floating logger
FlutterAwesomeLogger.setVisible(true);  // Show
FlutterAwesomeLogger.setVisible(false); // Hide

// Toggle visibility
FlutterAwesomeLogger.toggleVisibility();

Manage API Logs

// Get all API logs
final apiLogs = FlutterAwesomeLogger.getApiLogs();

// Get API logs by type
final successLogs = FlutterAwesomeLogger.getApiLogsByType(ApiLogType.success);
final errorLogs = FlutterAwesomeLogger.getApiLogsByType(ApiLogType.serverError);

// Clear API logs
FlutterAwesomeLogger.clearApiLogs();

⚙️ Settings Modal

🖱️ Accessing Settings

• App Bar Icon: Tap the settings icon (⚙️) in the logger history page app bar
• Modal Interface: Clean bottom sheet with organized configuration sections

🔧 Available Settings

💡 Usage Tips

• Immediate Changes: All settings take effect instantly - no app restart required
• Mobile Friendly: Modal handles keyboard input and different screen sizes
• Visual Feedback: Current behavior is clearly described for each setting
• Live Stats: See how many logs are currently stored as you adjust limits

📱 Example Configuration

// Initial configuration
loggerConfig: const AwesomeLoggerConfig(
  maxLogEntries: 500,
  enableCircularBuffer: true, // Replace oldest logs
  showFilePaths: true,
  showEmojis: true,
  useColors: true,
),

// Runtime changes via settings modal:
// - Change maxLogEntries to 1000
// - Toggle enableCircularBuffer to false
// - Turn off showEmojis
// All changes apply immediately!

🎨 Customization

The logger UI is highly customizable. You can:

• Change colors and themes
• Customize the floating button appearance
• Configure log display formats
• Add custom filters and search options
• Pause/resume logging as needed
• Control logging behavior with simple configuration