flog 0.2.1 flog: ^0.2.1 copied to clipboard
A feature based logging library that helps filter logs and keep the console clean.
A feature based logging library that helps filter logs and keep the console clean.
Overview #
The goal of this package is to maintain a clean console by filtering logs based on features.
This allows to keep all logs, and to optionally allow featured specific logs to print to console.
Flog enables customization to printed logs, by changing its color, boldness, and background. Making it easy to spot different logs types.
Flog has an open API to easily integrate any analytic tools or services, by using its delegate
feature.
Getting Started #
Set Up #
Although Flog works right without any initial set up, the API is open to set up logs.
Flog.setUp(
label: String Function(DateTime date, String tag, String? feature)
allowLog: bool Function(),
ansiColorDisabled: bool,
useCleanStackTrace: bool,
formats: FlogFormats(
error: StatementFormat(
backgroundColor: BackgroundColor(FlogColors, {RGB rgb}),
textFormat: TextFormat(FlogColors, {bool isBold = false, RGB rgb})
),
fatal: StatementFormat,
important: StatementFormat,
info: StatementFormat,
nav: StatementFormat,
state: StatementFormat,
),
);
Label #
A string will be inserted as a prefix to each log. Provides the time stamp, the tag (type of log), and the feature (if provided, returns null
if none).
By default, the label uses only [tag].
Allow Log #
A check before every log. This is helpful to only print in development or profile modes. Printing should be avoided in release mode.
note: Allow log only affects printing to console, the delegate will still be called for every log.
default:
.allowLog = () {
if (kDebugMode) return true;
if (kProfileMode) return true;
if (kReleaseMode) return false;
return false;
};
Ansi Color Disabled #
Flog depends on AnsiColor to customize print statements. If customization is not working, try changing this value.
Reference https://pub.dev/packages/ansicolor for more info.
default:
.ansiColorDisabled = false,
Use Clean Stack Trace #
Flog depends on stack_trace to clean stack traces provided for flogFatal
and flogError
. To use Darts original Stack Trace, set to false
.
default:
.useCleanStackTrace = true,
Formats #
Customize how each log looks in console to easily distinguish between each different log type.
Set formats, or a specific log type, to null
to use the default console's settings.
default:
.formats = null,
Available Colors:
FlogColors {
black,
blue,
cyan,
gray,
green,
red,
white,
yellow,
custom,
}
To use a custom color, use FlogColors.custom
and provide an [RGB]
StatementFormat(
textFormat: TextFormat(
FlogColors.custom,
rgb: const RGB(red: 89, blue: 231, green: 245),
isBold: true,
),
),
note: To quickly test your formats, you can call:
Flog.runFormatTest();
Filtering #
Flog has the ability to filter specific logs to the console.
Flog.filter(
List<Object>?,
allowNav: bool,
allowState: bool,
);
To show all logs:
// by default, or by setting null, all logs will be shown
Flog.filter(null);
Features can be any type. enum, num, String, ect.
Example:
enum Filter {
one,
two,
}
void main() {
Flog.filter([Filter.one]);
flogInfo('this will always be printed');
flogInfo('this will NOT be printed', Filter.two);
flogInfo('this WILL be printed', Filter.one);
}
Allow State #
You have the ability to override all state logs.
false
will disable all state logs,
true
will enable all state logs, still filterable by features.
//default = true
Flog.filter(..., allowState: bool);
Allow Nav #
You have the ability to override all nav logs.
false
will disable all nav logs,
true
will enable all nav logs.
//default = true
Flog.filter(..., allowNav: bool);
Log Types #
There are 6 different logs available
state, nav, info, important, error, fatal
State #
flogState(Object? message, [Object? feature]);
This is intended for all state changes with your choice of State Management Provider.
You can pass an optional parameter, [feature], to add a Feature specific filter. If no feature is provided, it will always print to console. By providing a feature, the log with always show, unless Flog.filter(...)
contains a value.
Nav #
flogNav(Object? message);
This is intended for all navigation changes.
Info #
flogInfo(Object? message, [Object? feature]);
This is similiar to the basic print statement. All dev, testing, and non-important logs.
You can pass an optional parameter, [feature], to add a Feature specific filter.
Important #
flogImportant(Object? message);
This is intended for all important logs, logs that may require additional attention.
Use cases:
- Unexpected events
- Significant info
- Unwanted events
Error #
flogError(Object? object, [dynamic stackTrace]);
This is intended for logs of an exception or an undesired result.
Fatal #
flogFatal(Object? object, [dynamic stackTrace]);
This is intended for logs that represent an irreparable situation.
Observing logs #
Each corresponding log type has a delegate that can be used to incorporate analytics or services.
Flog.delegate = FlogDelegate(
flogState: void Function(Object? object, [Object? feature]),
flogNav: void Function(Object? object),
flogInfo: void Function(Object? object, [Object? feature]),
flogImportant: void Function(Object? object),
flogError: void Function(Object? object, [dynamic stackTrace]),
flogFatal: void Function(Object? object, [dynamic stackTrace]),
);
Starware #
Flog is Starware.
This means you're free to use the project, as long as you star its GitHub repository.
Your appreciation makes us grow and glow up. ⭐