logd

Pub Version Pub Points License: BSD 3-Clause

A flexible, hierarchical logging library for Dart and Flutter applications. logd provides customizable logging with support for multiple handlers, formatters, sinks, and filters, making it ideal for debugging, monitoring, and production logging in complex projects.

Features

  • Hierarchical Logger Tree: Dot-separated case-insensitive naming for inheritance (e.g., 'app.ui' inherits from 'app').
  • Pure Dart Support: Fully compatible with standalone Dart environments.
  • Dynamic Inheritance with Caching: Dynamic configurations; configurations dynamically propagate down the hierarchy tree; cached configurations for performance.
  • Customizable Layouts: Boxed, JSON, or custom formatters.
  • Customizable Outputs: Console, File, and Network Sinks; Size/Time based File Rotation; Level and Regex Filters.
  • Stack Trace Integration: Automatic caller extraction, configurable frame counts per level, ignoring packages like 'flutter'.
  • Timestamp/Timezone Support: Custom patterns with timezone support (e.g., 'yyyy-MM-dd HH:mm:ss ZZZ').
  • Multi-line Buffers: Atomic logging for complex messages.
  • Flutter Integration: Attach to FlutterError and uncaught exceptions.
  • Immutable and Efficient: Loggers act as lightweight proxies to configurations; lazy inheritance and caching for optimal performance.

Installation

Add logd to your pubspec.yaml:

dependencies:
  logd: ^latest_version

Then run:

dart pub get

For Flutter:

flutter pub get

Usage

Basic Logging

Import and get a logger:

import 'package:logd/logd.dart';

final logger = Logger.get('my.app');
logger.info('Application started');

Configuring Loggers

Set global or specific configs:

Logger.configure('global', logLovel: LogLevel.info);
Logger.configure('my.app', enabled: true, includeFileLineInHeader: true);

Logging with Details

Include errors and stack traces:

try {
// Code that may fail
} catch (e, stack) {
logger.error('Operation failed', error: e, stackTrace: stack);
}

Multi-line Buffers

For atomic multi-line logs:

final buffer = logger.debugBuffer;
buf?.writeln('Step 1: Initialize');
buf?.writeln('Step 2: Process data');
buf?.sync();

Hierarchical Inheritance

Child loggers inherit from parents dynamically:

final parent = Logger.get('app');
final child = Logger.get('app.ui');

Logger.configure('app', logLevel: LogLevel.warning);
// 'app.ui' now uses warning level unless overridden

Advanced:

Freezing Inheritance

Snapshot configs down the Logger hierarchy tree to children for isolation or optimization:

parent.freezeInheritance();

Attaching to Flutter

Capture framework errors:

Logger.attachToFlutterErrors();

Attach to Uncaught Errors

  runZonedGuarded(
    // Run your app here
    ,
    (error, stack) {
      Logger.get().error(
        'Caught uncaught error in zone',
        error: error,
        stackTrace: stack,
      );
    },
);

Examples

Custom Handler

final handler = Handler(
  formatter: JsonFormatter(),
  sink: FileSink('logs/app.log'),
  filters: [LevelFilter(LogLevel.warning)],
);
Logger.configure('global', handlers: [handler]);

FileRotation for FileSink

Time Based

FileSink(
  'logs/app.log',
  fileRotation: TimeRotation(
    interval: Duration(days: 1),
    nameFormatter: Timestamp(formatter: 'yyyy-MM-dd'),
    backupCount: 7,
    compress: true,
  ),
);
// Rotated files: app-2025-11-11.log.gz, etc.
// (current logs always to 'app.log').

Size Based

FileSink(
  'logs/app.log',
  fileRotation: SizeRotation(
    maxSize: '10 MB',
    backupCount: 5,
    compress: true,
  ),
);
// Rotated files: app.1.log.gz, app.2.log.gz, etc. (index 1 is newest).

Custom Timestamp

final ts = Timestamp(formatter: 'yyyy-MM-dd HH:mm:ss Z', timeZone: TimeZone.utc());
Logger.configure('global', timestamp: ts);

For more examples, see the example/ directory.

Contributing

Contributions are welcome! Please read CONTRIBUTING for details.

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

Libraries

logd