trace 0.0.6-prerelease copy "trace: ^0.0.6-prerelease" to clipboard
trace: ^0.0.6-prerelease copied to clipboard

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

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

# 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
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.

7
likes
140
pub points
37%
popularity
screenshot

Publisher

verified publishernikosportolos.com

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

Repository (GitHub)
View/report issues
Contributing

Topics

#trace #logging #print #console #file

Documentation

Documentation
API reference

License

MIT (LICENSE)

Dependencies

ansix, collection, data_class_plugin, date_time_format, meta, path, rxdart, stack_trace

More

Packages that depend on trace