trace

Description:

trace

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);
copied to clipboard
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,
);
copied to clipboard
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
});
copied to clipboard
Dispose

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

await Trace.dispose();
copied to clipboard
Loggers #


Console


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


File


FileLogger({
final String? path,
final String? filename,
final LoggerTheme? theme,
super.filter,
super.level,
})
copied to clipboard
Customization #
Filter
Defines a set of rules based on which it will be decided if the logger should print the message.
LogFilter({this.rules})
copied to clipboard
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);
copied to clipboard
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();
}
copied to clipboard

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);
copied to clipboard


Contribution #
Check the contribution guide
if you want to help with Trace.
Changelog #
Check the changelog
to learn what's new in Trace.

License

For personal and professional use. You cannot resell or redistribute these repositories in their original state.

Share

• Share on Facebook
• Share on Twitter