logging library Jetleaf

🪵 Jetleaf Logging Subsystem & Structured Diagnostics

This library provides the centralized, high-performance structured logging and diagnostics infrastructure for the Jetleaf framework.

It encapsulates:

  • Logger Abstractions: Log, LogFactory, LogLevel.
  • Standard Printers: PrettyPrinter, FlatStructuredPrinter, FmtPrinter.
  • Output Sinks: ConsoleLogger, FileLogger, and configurable stream destinations.
  • Configurable Log Formatting: Timestamps, thread/isolate identifiers, caller locations, and ANSI colors.

📊 Log Level Hierarchy

┌────────────────────────────────────────────────────────────────────────┐
│                          LogLevel Priority Order                       │
├────────────────────────────────────────────────────────────────────────┤
│ TRACE  ──►  DEBUG  ──►  INFO  ──►  WARN  ──►  ERROR  ──►  FATAL        │
├────────────────────────────────────────────────────────────────────────┤
│ • Lowest: TRACE (fine-grained tracing, loop iterations, internal hops) │
│ • Default: INFO (standard lifecycle messages, service readiness)       │
│ • Highest: FATAL (unrecoverable system failure requiring termination)  │
└────────────────────────────────────────────────────────────────────────┘

📦 Exports Categorization

🪵 Core Logger Contracts

  • Log — primary logging interface with trace, debug, info, warn, error, and fatal methods.
  • LogFactory — factory for retrieving named and class-scoped Log instances.
  • LogLevel — enumeration defining log severities and threshold comparisons.

🖨️ Formatters & Printers

  • PrettyPrinter — human-friendly multi-line console printer with color-coded borders and stack traces.
  • FlatStructuredPrinter — compact single-line printer optimized for cloud log collectors (Datadog, CloudWatch).
  • FmtPrinter — custom template-based formatter.

🎯 Usage Example: Class-Scoped Logging & Dynamic Log Levels

import 'package:jetleaf/logging.dart';

class OrderProcessor {
  static final Log _logger = LogFactory.getLog(OrderProcessor);

  void processOrder(String orderId, double amount) {
    _logger.info('Processing order: $orderId for \$$amount');

    try {
      if (amount <= 0) {
        throw ArgumentError('Order amount must be positive');
      }
      _logger.debug('Order $orderId validated successfully.');
    } catch (e, stackTrace) {
      _logger.error('Failed to process order $orderId', e, stackTrace);
    }
  }
}

void main() {
  final processor = OrderProcessor();
  processor.processOrder('ORD-101', 49.99);
  processor.processOrder('ORD-102', -10.0);
}

Classes

AnsiColor
A utility class to apply ANSI terminal color codes to strings.
AnsiOutput
A utility class for formatting terminal output using ANSI colors and background styles.
DefaultLoggingListener
A default implementation of LoggingListener that outputs logs to the console.
Log
A convenient logging utility built on top of LogFactory.
LogCommons
A utility class that provides common styling and symbols for different LogLevels.
LogConfig
Configuration class that controls the appearance and content of log output.
LogFactory
A base class for building structured logging mechanisms within Jet-based applications.
Logger
A flexible and extensible logging interface.
LoggingListener
A listener interface for reacting to logging events within an application.
LogPrinter
A base class for implementing custom log output formatting.
LogProperties
A small, thread-safe global registry for logging configuration and diagnostic properties within Jetleaf.
LogRecord
A LogRecord represents a single logging event captured by the logging system.

Enums

LogLevel
Defines various levels of logging severity for controlling logging output.
LogStep
Defines individual components (steps) that can be included in log output.
LogType
Specifies the overall formatting strategy used for log output.

Properties

console → Logger
Global singleton logger instance for convenience.
final