log_4_dart_2

Description:

log 4 dart 2

Log 4 Dart 2 #
A dart package for advanced logging, with multiple and configurable appenders.
Table of Contents #

Log 4 Dart 2

Table of Contents
Preamble
Install

pubspec.yaml


Import
Usage

Setup Logger
Logging


Appender And Configuration

ConsoleAppender
FileAppender
HttpAppender
EmailAppender
MySqlAppender
Adding Custom Appender
Log Format
Rotation Cycle
Example Configuration


Changelog
Copyright And License



Preamble #
The package is under construction and still needs some tweeks and code improvements!
Install #
pubspec.yaml #
Update pubspec.yaml and add the following line to your dependencies.
dependencies:
log_for_dart_2: ^1.1.0
copied to clipboard
Import #
Import the package with :
import 'package:log_4_dart_2/log_4_dart_2.dart';
copied to clipboard
Usage #
Setup Logger #
There are two ways to setup the Logger.

Store the logger configuration in seperate json file and pass the full name of the file to the initFromFile() method.
Create a Map<String,dynamic> that holds the configuration and pass it to the init() method.

void main(List<String> arguments){
// Init the logger from a configuration file
Logger.initFromFile('/path/to/log4d.json');
// Or by using a Map<String,dynamic>
Logger.init(config);
}
copied to clipboard
Note that Logger.init(...) has to be called only once, preferably in the main method. It configures
an instance internally that can then be accessed statically through Logger (or Logger.instance).
Take a look at Example Configuration for a full example.
Logging #
The Logger offers multiple methods for logging on different levels.
static String TAG = 'TestClass';
Logger.debug('Lorem Ipsum', tag: TAG);
Logger.trace('Lorem Ipsum', tag: TAG);
Logger.info('Lorem Ipsum', tag: TAG);
Logger.warn('Lorem Ipsum', tag: TAG);
Logger.error('Lorem Ipsum', tag: TAG);
Logger.fatal('Lorem Ipsum', tag: TAG);
copied to clipboard
Note that as of version 1.0.0, the old way has to be slightly adapted: the methods Logger().debug(...)
are now called Logger().logDebug(...) (respectively per level).
There are two ways that are considered best for logging from a client context:
1: Directly through the static log methods on the Logger class:
class PlainClient {
void doStuff() {
Logger.debug('message', tag: 'some tag');
}
}
copied to clipboard
2: Through the mixin Log4Dart. Note that the log methods are here called e.g. logDebug(...) to
make their origin within the client code clear.
class Client with Log4Dart {
void doStuff() {
logDebug('message', tag: 'some tag');
}
}
copied to clipboard
Note that in both cases, the Logger has to be initialized, e.g in main:
void main() async {
await Logger.init(kLog4DartConfig);
...
}
copied to clipboard
Appender And Configuration #
ConsoleAppender #
The ConsoleAppender is a simple appender that appends every log entry to the console output.

type = The type of the appender. This has to be set to CONSOLE.
dateFormat = The date format used for the appender. Default = yyyy-MM-dd HH:mm:ss.
level = The loglevel for this appender.
format = The format for the log output. See Log format for more information.
brackets = bool to wrap all message blocks with brackets: [%d]. Message is excluded from this.

FileAppender #
The FileAppender appends every log entry to a logfile.

type = The type of the appender. This has to be set to FILE.
level = The loglevel for this appender.
format = The format for the log output. See Log format for more information
dateFormat = The date format used for the appender. Default = yyyy-MM-dd HH:mm:ss.
filePattern = The pattern used for the filename.
fileExtension = The fileextension. Default is "log".
path = The path to the file
rotationCycle = The rotation cycle for the appender. See Rotation Cycle. Default ist NEVER.

Note: If a path was specified, it must also exist!
HttpAppender #
The HttpAppender sends a log entry via HTTP POST request to a given url.

type = The type of the appender. This has to be set to HTTP.
dateFormat = The date format used for the appender. Default = yyyy-MM-dd HH:mm:ss.
level = The loglevel for this appender.
url = The url for the POST request.
headers = A list of headers where the name and value of the header a seperated by a ":". Example "Content-Type:application/json"

EmailAppender #
The EmailAppender sends a log entry via email to a given address.

type = The type of the appender. This has to be set to EMAIL.
dateFormat = The date format used for the appender. Default = yyyy-MM-dd HH:mm:ss.
level = The loglevel for this appender.
host = The smtp server.
user = The user for this server.
password = The password for the given user.
port = The port of the smtp server
fromMail = The sender email. As a default, the username is used.
fromName = The sender name.
to = A list of email addresses to send the email to.
toCC = A list of email addresses to receive a copy.
toBCC = A list of email addresses to receive a blind copy.
ssl = Whether to use ssl or not.
templateFile = Full path to a file containing the template to use to send via email. If no template is given the appender will send the LogRecord as JSON. You can use the same placeholders within your template that are used for the format setting. See Log format for more information.
html = Whether the given template is plaintext or html. Default is false.

Note: Due to the mailer package that is used to provide this appender, this works only for mail servers that need authorization by user/password.
MySqlAppender #
The MySqlAppender appends every log entry to a table in a mysql database.

type = The type of the appender. This has to be set to MYSQL.
level = The loglevel for this appender.
host = The host for the mysql database.
user = The user.
password = The password of the user.
port = The port of the host.
database = The database name.
table = The table to write to.

Create the table with the given statement. Replace $table with your desired table name.
CREATE TABLE `$table` (
`id` INT NOT NULL AUTO_INCREMENT,
`tag` VARCHAR(45) NULL,
`level` VARCHAR(45) NULL,
`message` VARCHAR(45) NULL,
`time` VARCHAR(45) NULL,
PRIMARY KEY (`id`));
copied to clipboard
Adding Custom Appender #
Log4Dart2 supports the usage of custom appenders. Create a class that extends the Appender and implements the append and init methods.
import 'package:log_4_dart_2/log_4_dart_2.dart';

class CustomAppender extends Appender {
@override
void append(LogRecord logRecord) {
// TODO: implement append
}

@override
void init(Map<String, dynamic> config, bool test, DateTime date) {
// TODO: implement init.
}

@override
Appender getInstance(){
return CustomAppender();
}

@override
String getType(){
return 'CustomAppender';
}
}
copied to clipboard
Register the custom appender in the Logger via the registerAppender() method before the logger is initialized.
Logger.instance.registerAppender(CustomAppender());
copied to clipboard
Log Format #
The format of the log entrys can be configured for some appender.

%d = The date.
%i = The identifier.
%t = The tag.
%l = The log level.
%m = The message.
%f = The file name with line and column number (e.g. package:my_project/chat_screen.dart(42:7))
%c = The class and method name with line number (e.g. ChatScreenState.getCurrentUser:42)

Additionally you can add MDC (Mapped Diagnostic Context) placeholders when the app is run in a Zone:

%X{

Best shown in an example:
void main() async {
await Logger.init(kLog4DartConfig);

// We define values to zone as 3rd param: zoneValues
// This cannot run within the test callback, for the moment this works directly or further down the line...
await runZonedGuarded(() async {
// App running, we set some vars somewhere down the line to zone:
if (Zone.current['LOG_SESSION_HASH_KEY'] != null) {
// sets LOG_SESSION_HASH_KEY to 865a15
Zone.current['LOG_SESSION_HASH_KEY'].add(generateMd5Fingerprint('Some data like app start timestamp'));
}
// Then we log and hand off to the logging library
Logger.debug('hello world');
}, (Object error, StackTrace stackTrace) {
print(error);
}, zoneValues: {
// sets LOG_DEVICE_HASH_KEY to 8634e3c65a15
'LOG_DEVICE_HASH_KEY': [generateMd5Fingerprint('Data that is consistent per platform like values delivered by device_info_plus')],
vLOG_SESSION_HASH_KEY': [], // yet empty, set further down the line
});
}

// Just an idea...
String generateMd5Fingerprint(String input) {
return md5.convert(utf8.encode(input)).toString().substring(0, 6);
}
}
copied to clipboard
With this format setup
'format': '%d%i%X{logging.device-hash}%X{logging.session-hash}%t%l%c %m %f'
copied to clipboard
It should print something like this, where the two parts [634e3c] and [865a15] can be useful for log analysis:
[2022-04-28 14:44:26.934][CONSOLE][634e3c][865a15][tag-512][DEBUG][ClientWithLogEx.logStuff:60] hello world [package:my_project/chat_screen.dart(60:5)]
copied to clipboard
Examples :

"%d %i %t %l %m"
"This log entry was created on %d from class %t from thread %i. It has the level %l and the message %m"

Example for an html template :
<h1>Log Event</h1>
<p>Message: %m</p>
<p>Class: %t</p>
<p>Time: %d</p>
<p>Level: %l</p>
copied to clipboard
Rotation Cycle #
The rotation cycle can be configured for some appender. It defines how offen a new file is created to store the logging data.

NEVER (Never rotate)
DAY (Rotate on a daily basis)
WEEK (Rotate on weekly basis)
MONTH (Rotate on monthly basis every first day of the month)
YEAR (Rotate on a yearly basis every first day of the year)

Example Configuration #
Some configuration examples with all possible appenders and their settings.
var config = {
'appenders': [
{
'type': 'CONSOLE',
'format': '%d%i%t%l%c %m %f',
'level': 'TRACE',
'dateFormat': 'yyyy-MM-dd HH:mm:ss.SSS',
'brackets': true,
'mode': 'stdout'
},
{
'type': 'FILE',
'dateFormat' : 'yyyy-MM-dd HH:mm:ss',
'format': '%d %i %t %l %m',
'level': 'INFO',
'filePattern': 'log4dart2_log',
'fileExtension': 'txt',
'path': '/path/to/'
'rotationCycle': 'MONTH'
},
{
'type': 'EMAIL',
'dateFormat' : 'yyyy-MM-dd HH:mm:ss',
'level': 'INFO',
'host': 'smtp.test.de',
'user': '[email protected]',
'password': 'test',
'port': 1,
'fromMail': '[email protected]',
'fromName': 'Jon Doe',
'to': [
'[email protected]',
'[email protected]'
],
'toCC': [
'[email protected]',
'[email protected]'
],
'toBCC': [
'[email protected]',
'[email protected]'
],
'ssl': true,
'templateFile': '/path/to/template.txt',
'html': false
},
{
'type': 'HTTP',
'dateFormat' : 'yyyy-MM-dd HH:mm:ss',
'level': 'INFO',
'url': 'api.example.com',
'headers': [
'Content-Type:application/json'
]
},
{
'type': 'MYSQL',
'level': 'INFO',
'host': 'database.example.com',
'user': 'root',
'password': 'test',
'port': 1,
'database': 'mydatabase',
'table' : 'log_entries'
}
]
};
copied to clipboard
{
"appenders": [
{
"type": "CONSOLE",
"dateFormat" : "yyyy-MM-dd HH:mm:ss",
"format": "%d %i %t %l %m",
"level": "INFO"
},
{
"type": "FILE",
"dateFormat" : "yyyy-MM-dd HH:mm:ss",
"format": "%d %i %t %l %m",
"level": "INFO",
"filePattern": "log4dart2_log",
"fileExtension": "txt",
"path": "/path/to/",
"rotationCycle": "MONTH"
},
{
"type": "EMAIL",
"dateFormat" : "yyyy-MM-dd HH:mm:ss",
"level": "INFO",
"host": "smtp.test.de",
"user": "[email protected]",
"password": "test",
"port": 1,
"fromMail": "[email protected]",
"fromName": "Jon Doe",
"to": [
"[email protected]",
"[email protected]"
],
"toCC": [
"[email protected]",
"[email protected]"
],
"toBCC": [
"[email protected]",
"[email protected]"
],
"ssl": true,
"templateFile": "/path/to/template.txt",
"html": false
},
{
"type": "HTTP",
"dateFormat" : "yyyy-MM-dd HH:mm:ss",
"level": "INFO",
"url": "api.example.com",
"headers": [
"Content-Type:application/json"
]
},
{
"type": "MYSQL",
"level": "INFO",
"host": "database.example.com",
"user": "root",
"password": "test",
"port": 1,
"database": "mydatabase",
"table" : "log_entries"
}
]
}
copied to clipboard
Changelog #
For a detailed changelog, see the CHANGELOG.md file
Copyright And License #
MIT License
Copyright (c) 2020 Ephenodrom
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.