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.

Platform Support

Installation & Quick Start

dependencies:
  pd_log: ^0.10.0

import 'package:pd_log/pd_log.dart';

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

    // Console colors: disabled by default
    ansiEnabled: true,
    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.
• ansiEnabled: Whether to wrap console output with ANSI colors (default false). File writes are always plain text.

Example: Disable ANSI for Apple console (plain text output):

import 'dart:io';
PDLog.updateConfigure(ansiEnabled: !(Platform.isIOS || Platform.isMacOS));

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

Example Project

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

License

MIT (see root LICENSE).