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

Colorful Style (Recommended)

ℹ️  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.