pd_log #

Current version: v0.8.2 (2026-07-06)

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.

Platform Support #

Installation & Quick Start #

dependencies:
  pd_log: ^0.8.2

import 'package:pd_log/pd_log.dart';

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

    // Console colors: disabled by default
    ansiEnabled: true,
    nativeFileLoggingEnabled: true,
  ));
  PDLog.i('pd_log is ready');
}

Configuration notes:

• nativeFileLoggingEnabled: Enable local file writing (Dart-managed, unified buffering and flush); no-op on Web.
• ansiEnabled: Whether to wrap console/platform 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.flushNativeLogs() (triggers Dart writer flush; platform side is stub)
• 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})

Documentation #

Architecture overview: Dart manages file writing and buffering; platform side provides console output, log root path, and file event listening. File enumeration and deletion are implemented in Dart; platform methods return stub defaults for API consistency.

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

Example Project #

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

License #

MIT (see root LICENSE).