contextual_logging

Description:

contextual logging

contextual_logging #
✏️ A mixin for Dart classes that brings contextual logging functionality to your class.
Print messages like this w/o any effort.
10:03:00 [I] MyController : Initializing ...
10:03:01 [I] MyController : Initialized!
copied to clipboard

🌐 Is built on top of the logger package.

Table of contents #

What's contextual logging?
Logger

The mixin
Configuration

Context
Custom logger


Default logger config everywhere


Contextual log printer

What's this?
Configuring the printer

Example
Log level label





What's contextual logging? #
We all know log messages. They are printed to the console, to the files or whatever. Dart provides us with methods for logging like:
print('A message');
debugPrint('Another message');
copied to clipboard
Good enough to debug. But when you actually need to investigate users' journey, it is not. You'll need context. The context here answers the question who has printed the message?.
Adding context could be done like this:
print('My Controller : A message');
debugPrint('My Controller : Another message');
copied to clipboard
... and it will work. Though to write the context every time is pretty boring. This is what contextual_logging solves.
Logger #
The mixin #
Attach the mixin it to your class that you want to use for logging:
class MyController with ContextualLogging
copied to clipboard
And now go for it!
class MyController with ContextualLogging {
Future<void> init() async {
log.i('Initializing ...'); // <-- Access logging via the log field
await fetchData();
log.i('Initialized!');
}
}
copied to clipboard
You will see this in the console:
10:03:00 [I] MyController : Initializing ...
10:03:01 [I] MyController : Initialized!
copied to clipboard
Configuration #
By default, a logger is created for every object that has a ContextualLogging mixin attached to it. Once you attach the mixin, you'll be able to configure the logger for this object.
Context
logContext property is what Contextual Logger adds to the log message in front of the main message. By default it has a value of this.toString(). Override it to whatever you want:
class MyController with ContextualLogging {
@override
String get logContext => 'SomeOtherContext`;

void test() {
log.i('Test'); // 19:12:00 [I] SomeOtherContext : Test
}
}
copied to clipboard
Custom logger
If you want to use a custom logger, feel free to override the customLogger property:
class MyController with ContextualLogging {
@override
Logger get customLogger => Logger(/* Configure it in whatever way you want! */);

void test() {
log.i('Test'); // Still access it via the `log` property!
}
}
copied to clipboard
Default logger config everywhere #
If you want to reconfigure loggers for all the object at once, do this before your app starts:
// ContextualLogger mixin uses this defaultLogger by default to get a logger for the object it was attached to.
ContextualLoggingConfig.defaultLogger = (forObject) => MyBeautifulLogger(forObject);
copied to clipboard
Once you do it, every ContextualLogger mixin will create loggers like this.
Contextual Log Printer #

💡 A printer is what formats your messages.

What's this? #
When setting the ContextualLoggingConfig.defaultLogger property, you can create a logger and provide any printer you want. Or you can use the default printer used by ContextualLogger, the ContextualLogPrinter. This printer is what makes the messages look like this:
12:01:00 [I] SomeOtherContext : Test
copied to clipboard
Instead of this:
Test
copied to clipboard
Configuring the printer #
There are plenty of properties you can change:



Property
Type
Description
Default




forObject
Object
The object for which the logger was created. Use a string if you want to have it as a prefix.
this


timeFormat
DateFormat
Format of the current timestamp
HH:mm:ss


timeInUtc
bool
Whether the current timestamp must be in UTC
false


printTime
bool
Whether to print the timestamp
true


logLevelLabel
Function
Log level prefix for messages
[I], [W] etc



Example
So imagine you've overridden the printer like this:
ContextualLoggingConfig.defaultLogger = (forObject) {
return Logger(
printer: ContextualLogPrinter(
forObject: forObject,
printTime: false, // Note!
),
);
};

// This will make your messages look like this:

[I] MyController : A message
copied to clipboard
Log level label
Log level lebel is what allows you to distinguish the level of a message. The logger package allows you to use these levels:



Level
Function
Default
Emoji




Verbose
log.v
[V]
None


Debug
log.d
[D]
🐛


Info
log.i
[I]
💡


Warning
log.w
[W]
⚠️


Error
log.e
[E]
⛔️


Wtf
log.wtf
[WTF]
🗿


Nothing
log.log(Level.nothing, ...)
None
None



Override the logLevelLabel property to make your own prefixes!
ContextualLoggingConfig.defaultLogger = (forObject) {
return Logger(
printer: ContextualLogPrinter(
forObject: forObject,
logLevelLabel: (level) {
/* Return a prefix for the given level! */
},
),
);

// Or do this to enable emojis level!
ContextualLoggingConfig.defaultLogger = (forObject) {
return Logger(
printer: ContextualLogPrinter(
forObject: forObject,
logLevelLabel: ContextualLogPrinter.emojiLevelLabel,
),
);
copied to clipboard