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.
• Structured logging: ECS (Elastic Common Schema) format support for ELK integration.

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.12.0

New API (Recommended)

import 'package:pd_log/pd_log.dart';

void main() {
  PDLog.configureWith(
    consoleConfig: const ConsoleConfig(
      minLevel: LogLevel.debug,
      showTimestamp: true,
      showCaller: true,
      theme: LogTheme.dark,
      defaultTag: 'MyApp',
    ),
    fileConfig: FileConfig(
      enabled: true,
      minLevel: LogLevel.info,
      logFormat: LogFormat.ecs,
      retentionStrategy: LogRetentionStrategy.days,
      retentionCount: 7,
    ),
  );
  PDLog.i('pd_log is ready');
}

Old API (Deprecated)

import 'package:pd_log/pd_log.dart';

void main() {
  PDLog.configure(const PDLogConfig(
    minLevel: LogLevel.debug,
    theme: LogTheme.light,
    fileLoggingEnabled: true,
  ));
  PDLog.i('pd_log is ready');
}

Configuration

ConsoleConfig

Controls console output behavior:

ConsoleConfig(
  enabled: true,           // Enable console output
  minLevel: LogLevel.debug, // Minimum level to output
  defaultTag: 'MyApp',     // Default tag when not specified
  showTimestamp: true,     // Show timestamp in output
  showCaller: true,        // Show caller information
  theme: LogTheme.dark,    // Theme for colors and styles
)

FileConfig

Controls file writing behavior:

FileConfig(
  enabled: true,                        // Enable file writing
  minLevel: LogLevel.info,              // Minimum level to write to file
  logFormat: LogFormat.ecs,             // Output format: simpleJson or ecs
  flushIntervalMs: 2000,               // Buffer flush interval (ms)
  maxBufferEntries: 100,               // Max buffer entries before flush
  maxBufferBytes: 64 * 1024,           // Max buffer bytes before flush
  retentionStrategy: LogRetentionStrategy.days, // Log rotation strategy
  retentionCount: 7,                   // Number of days/months/years to keep
  showViewer: true,                    // Show embedded log viewer button
)

LogFormat

Two output formats are supported:

simpleJson (default):

{
  "level": "I",
  "tag": "App",
  "time": "2026-07-09T10:00:00.000",
  "caller": "main",
  "msg": "Application started"
}

ecs (Elastic Common Schema):

{
  "@timestamp": "2026-07-09T02:00:00.000Z",
  "log.level": "info",
  "log.logger": "App",
  "message": "Application started",
  "log.origin": {
    "file.name": "main.dart",
    "function": "main",
    "line": 10
  },
  "ecs": {
    "version": "8.15.0"
  }
}

Theming

// Use built-in themes
PDLog.configureWith(
  consoleConfig: const ConsoleConfig(
    theme: LogTheme.light,  // Light theme
    // theme: LogTheme.dark,   // Dark theme
    // theme: LogTheme.noColor, // No color (for terminals without ANSI support)
  ),
);

Example: Disable ANSI colors for Apple Console.app:

import 'dart:io';

final theme = Platform.isMacOS || Platform.isIOS
    ? LogTheme.noColor
    : LogTheme.light;

PDLog.configureWith(
  consoleConfig: ConsoleConfig(theme: theme),
);

Embedded Log Viewer

Enable the floating button to access the inline log viewer:

// Enable floating button in configuration
PDLog.configureWith(
  fileConfig: FileConfig(
    enabled: true,
    showViewer: true,
  ),
);

// Or control programmatically
PDLog.showViewer();   // Show floating button
PDLog.hideViewer();   // Hide floating button
PDLog.toggleViewer(); // Toggle visibility

Features:

• Overlay-based floating button (always on top)
• Draggable button position
• Inline log viewing page with filtering, search, sorting
• Real-time log monitoring
• Log export and copy functionality
• Automatic format detection (simpleJson / ecs)

Key API (Selected)

• Log output: PDLog.v/d/i/w/e(Object? message, {String? tag})
• Configure: PDLog.configureWith({ConsoleConfig? consoleConfig, FileConfig? fileConfig})
• 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
• Embedded log viewer: PDLog.showViewer(), PDLog.hideViewer(), PDLog.toggleViewer() — overlay-based floating button with inline log viewing page supporting filtering, search, sorting, and export

ELK Integration

pd_log supports ECS (Elastic Common Schema) format for seamless integration with ELK stack:

PDLog.configureWith(
  fileConfig: FileConfig(
    enabled: true,
    logFormat: LogFormat.ecs,
  ),
);

Logstash configuration example:

input {
  file {
    path => "/logs/**/*.log"
    codec => "json_lines"
  }
}

output {
  elasticsearch {
    hosts => ["http://localhost:9200"]
    index => "pd_log-%{+YYYY.MM.dd}"
  }
}

The ECS format includes standard fields like @timestamp, log.level, log.logger, log.origin, and error.stack_trace for easy indexing and visualization in Kibana.

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).