trace 0.0.3-prerelease

Trace is a minimalistic logger for your Dart & Flutter projects, that uses AnsiX to print customizable messages in terminal and export log files.

Trace

Trace is a minimalistic logger for your Dart & Flutter projects, that uses AnsiX to print customizable messages in terminal and export log files.

This is a pre-release version of Trace, so using it in a production environment is not recommended yet.

Table of contents

• Usage
  • Trace
    • Register/unregister loggers
    • Log Levels
    • Logging methods
    • Stream
    • Dispose
  • Loggers
    • Console
    • File
  • Customization
    • Filter
      • Rules
    • Theme
• Examples
• Contribution
• Changelog

Usage

Trace

Trace is a global static class that handles all logging.

All you need to do is register your desired loggers, customize them if you want and just use the Trace logging methods.

Register/unregister loggers

final Logger logger = ConsoleLogger();

// Register a new console logger
Trace.registerLogger(logger);

// Unregister the console logger
Trace.unregisterLogger(logger);

Logging

  Trace.verbose('This is a verbose test message');
  Trace.debug('This is a debug test message');
  Trace.info('This is an info test message');
  Trace.success('This is a success test message');
  Trace.warning('This is a warning test message');
  Trace.error(
    'This is an error test message',
    Exception('Random exception'),
    StackTrace.current,
  );
  Trace.fatal(
    'This is a fatal test message',
    Exception('Critical exception'),
    StackTrace.current,
  );

Log levels

#	Level	Description
0	none	No logs will be displayed when this log level is selected.
1	verbose	This log level typically refers to a higher level of detail than the "DEBUG" log level and is used to provide even more information for troubleshooting and debugging purposes.
2	debug	This log level is used to provide detailed debugging information that is only useful for developers during the development process.
3	info	This log level is used to provide general information about the state of the system or program, such as when it starts or stops.
4	success	This log level is used to provide general information about the state of the system or program, such as when it starts or stops.
5	warning	This log level is used to indicate potential issues or errors that could cause problems, but are not critical.
6	error	This log level is used to indicate errors that have occurred, but are not fatal to the system or program.
7	fatal	This log level is used to indicate critical errors that could cause the system or program to fail or crash.

Stream

Trace.stream.listen((LogEntry entry) {
  // Custom log entry handling
});

Dispose

Don't forget to dispose Trace so there's no memory leaks, especially when using [FileLogger].

await Trace.dispose();

Loggers

• Console

ConsoleLogger({
  final IOSink? ioSink,
  super.filter,
  super.level,
  final LoggerTheme? theme,
})

• File

FileLogger({
  final String? path,
  final String? filename,
  final LoggerTheme? theme,
  super.filter,
  super.level,
}) 

Customization

Filter

Defines a set of rules based on which it will be decided if the logger should print the message.

LogFilter({this.rules})

You can also check the custom_filter.dart in the examples folder for a usage sample.

Rules

A FilterRule decides whether a log message should be printed or not.

// Default out-of-the-box rules provided by Trace.

/// Returns a new instance of [DebugFilterRule].
factory FilterRule.debug() => const DebugFilterRule();

/// Returns a new instance of [LevelFilterRule].
factory FilterRule.level(final LogLevel level) => LevelFilterRule(level);

/// Returns a new instance of [ErrorTypeFilterRule].
factory FilterRule.error(final Type type) => ErrorTypeFilterRule(type);

Theme

A collection of properties used by [Trace] in order to format the log messages.

• colorMap

  A map of [AnsiColor] for each LogLevel.

• timestampFormat

  The format that will be used to print the timestamp of the log entry.

  Defaults to [H:i:s.vu].

  Accepts the following standard notations:

  • d : Day of month (01 - 31) - j : Day of month, without leading 0s (1 - 31)
  • D : An abbreviated textual representation of a day (Mon - Sun)
  • l : A textual representation of a day (Monday - Sunday)
  • S : Suffix of a day (st, th, nd)
  • z : The day of the year (starting from 0)
  • F : A textual representation of a month (January - December)
  • M : An abbreviated textual representation of a month (Jan - Dec)
  • m : Numeric representation of a month (01 - 12)
  • n : Numeric representation of a month, without leading 0s (1 - 12)
  • Y : Full numeric representation of a year (e.g. 2019)
  • y : A two digit representation of a year (e.g. 19)
  • a : Ante meridiem and post meridiem, lowercase (am or pm)
  • A : Ante meridiem and post meridiem, uppercase (AM or PM)
  • g : 12-hour format of an hour, without leading 0s (1 - 12)
  • h : 12-hour format of an hour (01 - 12)
  • G : 24-hour format of an hour, without leading 0s (0 - 23)
  • H : 24-hour format of an hour (00 - 23)
  • i : Minutes (0 - 59)
  • s : Seconds (0 - 59)
  • v : Milliseconds (0 - 999)
  • u : Microseconds (0 - 999)
  • e : System time zone identifier (Returns [DateTime.timeZoneName], which is provided by the operating system and may be a name or abbreviation.)
  • O : Difference to Greenwich Time (GMT) in hours (±0000)
  • P : Difference to Greenwich Time (GMT) in hours with a colon (±00:00)
  • T : Time zone abbreviation (Identifies the time zone from [DateTime.timeZoneName].)
  • c : ISO 8601 date (e.g. 2019-10-15T19:42:05-08:00)
  • r : RFC 2822 date (Tue, 15 Oct 2019 17:42:05 -0800)
  • U : Seconds since Unix Epoch
  • \ : Escape character

• stacktraceIndent

  Defines the amount of spaces that will be used to indent the stacktrace.

  Defaults to 4.

• sections

  Defines which [LogSection] will be printed and in what order.

  Defaults to [LogSection.timestamp, LogSection.level, LogSection.message]

• timestampTheme

  The [AnsiTextTheme] that will be used to print the timestamp of the log entry.

• timestampFormatter

  The [LogSectionFormatter] that will be used to format the timestamp of the log entry.

• levelTheme

  The [AnsiTextTheme] that will be used to print the level of the log entry.

• levelFormatter

  The [LogSectionFormatter] that will be used to format the level of the log entry.

• messageTheme

  The [AnsiTextTheme] that will be used to print the message of the log entry.

• messageFormatter

  The [LogSectionFormatter] that will be used to format the message of the log entry.

Examples

import 'package:trace/trace.dart';

void main() async {
  // Register your loggers
  Trace.registerLoggers([
    ConsoleLogger(),
    FileLogger(),
  ]);

  Trace.verbose('This is a verbose test message');
  Trace.debug('This is a debug test message');
  Trace.info('This is an info test message');
  Trace.success('This is a success test message');
  Trace.warning('This is a warning test message');
  Trace.error(
    'This is an error test message',
    Exception('Random exception'),
    StackTrace.current,
  );
  Trace.fatal(
    'This is a fatal test message',
    Exception('Critical exception'),
    StackTrace.current,
  );

  // Don't forget to dispose Trace
  await Trace.dispose();
}

• Output in console

• Output in file

You can also check the example folder for more samples.

FAQ

• Q: Nothing is printed out when running on release mode.

  A: The default formatter of all loggers contains the DebugFilterRule. If you want your loggers to print messages when running on release mode, you can override this behaviour by creating a new logger with debugOnly:false.

  final ConsoleLogger logger = ConsoleLogger(
    filter: DefaultLogFilter(
      LogLevel.verbose,
      debugOnly: false,
    ),
  );
    
  Trace.registerLogger(logger);
  

Contribution

Check the contribution guide if you want to help with Trace.

Changelog

Check the changelog to learn what's new in Trace.