LogPrism

A Flutter debug logging library that provides non-blocking, lightweight logging with file persistence. LogPrism uses Dart Isolates to ensure all log operations happen without affecting the main thread.

Features

  • Non-blocking logging: All log operations run in a separate Isolate
  • Beautiful console output: Colorful, formatted logs with emoji indicators
  • File persistence: Logs are automatically saved to local files with rotation
  • Capacity management: Automatic cleanup when storage limits are reached
  • Multiple display modes: 4 different display formats for both console and widgets
  • Debug widgets: Built-in UI components for viewing logs
  • Zero main thread impact: Logging never blocks your UI
  • Cross-platform colors: ANSI color support with automatic terminal detection
  • Configurable: Customizable log levels, file sizes, retention policies, and console styles

Getting started

Add LogPrism to your pubspec.yaml:

dependencies:
  log_prism: ^0.0.1

Quick Example

import 'package:log_prism/log_prism.dart';

void main() async {
  // Initialize LogPrism (optional - it will auto-initialize on first use)
  await LogPrism.instance.initialize();
  
  // Start logging
  LogPrism.instance.debug('Debug message');
  LogPrism.instance.info('Info message', 'MyTag');
  LogPrism.instance.warning('Warning message');
  LogPrism.instance.error('Error message', 'ErrorTag', StackTrace.current);
}

Usage

Basic Logging

import 'package:log_prism/log_prism.dart';

void main() async {
  // Initialize LogPrism (optional - it will auto-initialize on first use)
  await LogPrism.instance.initialize();
  
  // Start logging
  LogPrism.instance.debug('Debug message');
  LogPrism.instance.info('Info message', 'MyTag');
  LogPrism.instance.warning('Warning message');
  LogPrism.instance.error('Error message', 'ErrorTag', StackTrace.current);
}

Configuration

import 'package:log_prism/log_prism.dart';

void main() async {
  // Custom configuration
  const config = LogPrismConfig(
    minLevel: LogLevel.info,           // Only log info and above
    maxTotalSizeMB: 100,              // 100MB total storage limit
    maxFileSizeMB: 10,                // 10MB per file
    enableInRelease: false,           // Disable in release builds
    autoCleanup: true,                // Auto-delete old files
    minRetentionDays: 3,              // Keep logs for at least 3 days
    
    // Console output settings
    enableConsoleOutput: true,        // Enable colorful console output
    consoleStyle: ConsoleDisplayStyle.colorful,  // Use colorful style
    minConsoleLevel: LogLevel.info,   // Only show info and above in console
  );
  
  await LogPrism.instance.initialize(config: config);
}

Using the Log Viewer Widget

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

class MyDebugScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Debug Logs')),
      body: Column(
        children: [
          // Compact summary widget
          LogSummaryWidget(
            height: 60,
            showOnlyErrors: false,
            maxItems: 5,
          ),
          
          SizedBox(height: 16),
          
          // Full log viewer with different display modes
          Expanded(
            child: LogViewerWidget(
              displayMode: LogDisplayMode.compact,
              showTimestamp: true,
              showLevel: true,
              showTag: true,
              maxLineLength: 100,
              levelFilter: [
                LogLevel.info,
                LogLevel.warning,
                LogLevel.error,
              ],
            ),
          ),
        ],
      ),
    );
  }
}

Display Modes

LogPrism supports 4 different display modes:

  • Standard: [2024-01-01 10:30:15] [INFO] [tag] message
  • Compact: 10:30:15 I tag: message
  • Minimal: I: message
  • Oneline: Truncated format with tap-to-expand

Console Output

LogPrism provides beautiful, colored console output with 4 different styles:

Compact Style (Default)

10:30:15.123 ● INFO [MyTag] Application started successfully
10:30:16.456 ● WARN [Auth] Session will expire in 5 minutes
10:30:17.789 ● ERROR [Network] Connection failed: timeout

ℹ️  10:30:15.123 ● INFO [MyTag] │ Application started successfully
⚠️  10:30:16.456 ● WARN [Auth] │ Session will expire in 5 minutes
❌ 10:30:17.789 ● ERROR [Network] │ Connection failed: timeout
  └─ StackTrace:
     #0  NetworkService.connect (network_service.dart:42)
     #1  AuthManager.login (auth_manager.dart:23)

Console Display Styles

  • compact: Simple timestamped logs with level indicators
  • full: Complete timestamp with colorized levels
  • minimal: Just level and message
  • colorful: Enhanced with emojis and visual separators

Console Configuration

const config = LogPrismConfig(
  enableConsoleOutput: true,                    // Enable/disable console output
  consoleStyle: ConsoleDisplayStyle.colorful,   // Choose display style
  minConsoleLevel: LogLevel.info,               // Filter console output level
);

Colors are automatically detected and work on:

  • ✅ macOS Terminal, iTerm2
  • ✅ Linux terminals with ANSI support
  • ✅ Windows Terminal, PowerShell 7+
  • ✅ VS Code integrated terminal
  • ✅ IntelliJ/Android Studio console

Log Summary Widget

For status bar or dashboard use:

LogSummaryWidget(
  height: 50,
  showOnlyErrors: true,      // Show only warnings and errors
  maxItems: 3,               // Show up to 3 recent items
  autoScroll: true,          // Auto-scroll to latest
)

Manual File Management

// Force immediate flush of buffered logs
await LogPrism.instance.flush();

// Clean shutdown (optional)
await LogPrism.instance.dispose();

Architecture

LogPrism implements a multi-threaded architecture:

  1. Main Thread: Handles API calls through the LogPrism singleton
  2. Log Isolate: Processes all log operations asynchronously
  3. File Manager: Handles I/O, rotation, and capacity management
  4. Widgets: Read log files independently for display

Storage Management

Logs are stored in:

documents/logprism/
├── logs/
│   └── app_log_YYYY_MM_DD.txt
└── config/
    └── settings.json
  • Daily log file rotation
  • Automatic cleanup when total size exceeds limit
  • Oldest files deleted first (FIFO)
  • Minimum retention period respected

Performance

  • Zero UI blocking: All operations run in background Isolate
  • Batched writes: Multiple logs combined for efficiency
  • Configurable limits: Control storage and performance impact

Debug vs Release

By default, LogPrism is disabled in release builds. Enable with:

const config = LogPrismConfig(enableInRelease: true);

License

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

Libraries

log_prism