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 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.
final Logger logger = ConsoleLogger();
// Register a new console logger
Trace.registerLogger(logger);
// Unregister the console logger
Trace.unregisterLogger(logger);
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,
);
# | 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. |
Trace.stream.listen((LogEntry entry) {
// Custom log entry handling
});
Don’t forget to dispose Trace so there’s no memory leaks, especially when using [FileLogger].
await Trace.dispose();
ConsoleLogger({
final IOSink? ioSink,
super.filter,
super.level,
final LoggerTheme? theme,
})
FileLogger({
final String? path,
final String? filename,
final LoggerTheme? theme,
super.filter,
super.level,
})
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.
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);
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.
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.
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
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);
Check the contribution guide if you want to help with Trace.
Check the changelog to learn what’s new in Trace.