trace 0.0.5-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
• Web support
• 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.

Web support

Trace runs also on Flutter web applications! 🌍🚀

AnsiX, which is the core library for ANSI colors and styles, will automatically detect the web browser and deactivate all formatting when the browser doesn't support ANSI escape codes.

The supported web browsers are: Chrome (and other Chromium-based browsers), Opera and Edge. On all other browsers all text will still be printed, but with no ANSI formatting.

Please note that the FileLogger is no-operational when running on a web application.

Read more: https://github.com/nikosportolos/ansix/blob/main/.documentation/features/web_support.md#web-support

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.