pd_log 0.11.0

Cross-platform Flutter logging with pure Dart; buffered file writes; no platform channels.

pd_log

Lightweight, cross-platform Flutter logging plugin with unified Dart file buffering and platform event listening.

Features

• Multi-level logging: PDLog.v/d/i/w/e, JSON pretty-print, ANSI styling.
• Dart file buffering: Cross-platform unified write thread buffering with timed/threshold flush; platform side provides console output, root path, and directory event listening.
• File query & maintenance: List/delete logs, rotation cleanup, organize by year/month/day.
• Metadata tracking: Event ledger (NDJSON) and snapshot (JSON) auto-maintenance.
• Cross-platform unified: Web console output (no file writes), consistent API.
• Log file export: Export logs to system directories (Documents/Downloads/Desktop) or custom paths; supports developer file access for upload to server.
• Sensitive data masking: Independent mask processor with configurable strategies (full/keepPrefix/keepSuffix/keepBoth) and rules (field-based/regex).
• Log content search: Full-text keyword matching across log files with context lines and time range filtering.
• Embedded log viewer: Overlay-based floating button with inline log viewing page; supports filtering, search, sorting, and export.
• Theming system: Unified UI colors and ANSI styles management with preset themes (light/dark/noColor) and custom theme support.

Platform Support

Platform	Support	Notes
Android	✅	File logging, console output, file events (polling)
iOS	✅	File logging, console output, file events (polling)
macOS	✅	File logging, console output, file events (watcher)
Windows	✅	File logging, console output, file events (watcher)
Linux	✅	File logging, console output, file events (watcher)
Web	⚠️	Console output only, no file system access

Installation & Quick Start

dependencies:
  pd_log: ^0.11.0

import 'package:pd_log/pd_log.dart';

void main() {
  PDLog.configure(const PDLogConfig(
    minLevel: LogLevel.debug,

    // Use theme system for unified UI colors and ANSI styles
    theme: LogTheme.light,
    fileLoggingEnabled: true,
  ));
  PDLog.i('pd_log is ready');
}

Configuration notes:

• fileLoggingEnabled: Enable local file writing (Dart-managed, unified buffering and flush); no-op on Web.
• theme: Theme configuration for unified UI colors and ANSI styles (recommended). Supports LogTheme.light, LogTheme.dark, LogTheme.noColor, or custom themes.
• ansiEnabled: Deprecated, use theme instead. Whether to wrap console output with ANSI colors. File writes are always plain text.

Example: Use no-color theme for Apple Console.app (plain text output):

import 'dart:io';

// Disable ANSI colors for Apple Console.app
final theme = Platform.isMacOS || Platform.isIOS
    ? LogTheme.noColor
    : LogTheme.light;

PDLog.configure(const PDLogConfig(
  theme: theme,
));

Themes:

• LogTheme.light: Light theme with standard ANSI colors for light terminals
• LogTheme.dark: Dark theme with bright ANSI colors for dark terminals
• LogTheme.noColor: No-color theme for terminals that don't support ANSI

Key API (Selected)

• Log output: PDLog.v/d/i/w/e(Object? message, {String? tag})
• Flush buffer: PDLog.flushLogs() (triggers Dart writer flush)
• Query logs: PDLog.listLogFiles(...), listLogFilesByYear(...), listLogFilesByYearMonth(...) (supports ListOptions sorting and pagination)
• File path: PDLog.logFilePathIfExists(DateTime date)
• Read file: PDLog.readLogFileContent(String path) (Dart file reading)
• Metadata view: PDLog.metaLedgerContent(), PDLog.metaSummaryContent()
• Directory structure: PDLog.fileTreeString({int maxDepth = 6})
• Export logs: PDLog.exportLogs({LogExportStrategy strategy}), PDLog.exportLogsToPath(String targetPath)
• File access: PDLog.listLogFiles() returns List<PDLogFile> with path, size, and modified time for custom processing

Documentation

Architecture overview: Dart manages all logging operations including console output, file writing, and buffering. Platform service provides log root path and file event listening. File enumeration, deletion, and search are fully implemented in Dart; Web platform gracefully degrades to console-only output.

Detailed usage instructions, notes, and best practices are available in the documentation module:

• Documentation index: doc/README.md
• Specific documentation links:
  • Getting Started
  • Configuration
  • File Storage & Rotation
  • Query & Pagination
  • Metadata & History
  • Web Platform Differences
  • Styling & Formatting
  • File Reading Tools
  • Buffer Flush & Event Listening
  • Log Export
  • Log Masking
  • Log Search
  • Log Viewer
  • Theming System

Example Project

Minimal example located in example/ directory, runnable with flutter run.

License

MIT (see root LICENSE).