Trace

Trace

Pub Version Pub Publisher Pub Points

Build codecov Language License: MIT

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.

trace-example

Table of contents

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

#LevelDescription
0noneNo logs will be displayed when this log level is selected.
1verboseThis 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.
2debugThis log level is used to provide detailed debugging information that is only useful for developers during the development process.
3infoThis log level is used to provide general information about the state of the system or program, such as when it starts or stops.
4successThis log level is used to provide general information about the state of the system or program, such as when it starts or stops.
5warningThis log level is used to indicate potential issues or errors that could cause problems, but are not critical.
6errorThis log level is used to indicate errors that have occurred, but are not fatal to the system or program.
7fatalThis 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
examples
  • Output in file
file-example

You can also check the example folder for more samples.

Web support

Trace runs also on Flutter web applications! 🌍🚀

web-example

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.


You may also be interested in