1 # IRCNOW lib
2 
3 
4 ## Logger
5 
6 example usage:
7 ```perl
8 use strict;
9 use warnings;
10 
11 use lib qw(./lib);
12 use Logger;
13 
14 my $logger = new Logger(Logger->SUGAR, ":timestamp [:loglevel%5] :package%8 :fileline%10 :msg");
15 
16 $logger->debug("debug");
17 $logger->info("info");
18 $logger->warn("warn");
19 $logger->error("error");
20 
21 # output:
22 # 2023-07-02 19:22:03 [DEBUG] main     test.pl:12 debug
23 # 2023-07-02 19:22:03 [INFO ] main     test.pl:13 info
24 # 2023-07-02 19:22:03 [WARN ] main     test.pl:14 warn
25 # 2023-07-02 19:22:03 [ERROR] main     test.pl:15 error
26 ```
27 
28 ### formating the logger
29 
30 logger has these fields:
31 * timestamp
32 * loglevel
33 * package
34 * file
35 * fileline (file with line number)
36 * line
37 * msg
38 
39 prepend the field with a `:` and postfix the field with a `%` followed by a number. Add spaces in between.
40 ex:
41 
42 `:timestamp [:loglevel%5] :package%8 :fileline%10 :msg`
43 
44 note: if your field value is longer than the specified length, it will print out the full value.
45 ex: 
46 format: `:timestamp [:loglevel%2] :package%8 :fileline%10 :msg` 
47 result:
48 ```
49 2023-07-02 19:21:54 [DEBUG] main     test.pl    debug
50 2023-07-02 19:21:54 [INFO] main     test.pl    info
51 2023-07-02 19:21:54 [WARN] main     test.pl    warn
52 2023-07-02 19:21:54 [ERROR] main     test.pl    error
53 ```
54 
55 ### sugar vs json
56 
57 there are two options to print logs:
58 * sugar
59 * JSON
60 
61 JSON logging is meant for being picked up by services such as grafana or the elk stack.
62 Sugar logging is meant for human readable output to stdout. 
63 
64 example of JSON:
65 ```
66 { "level": "DEBUG", "msg": "debug", "package": "main", "file": "test.pl:12" }
67 { "level": "INFO", "msg": "info", "package": "main", "file": "test.pl:13" }
68 { "level": "WARN", "msg": "warn", "package": "main", "file": "test.pl:14" }
69 { "level": "ERROR", "msg": "error", "package": "main", "file": "test.pl:15" }
70 ```
71 
72 example of Sugar:
73 ```
74 2023-07-02 19:22:03 [DEBUG] main     test.pl:12 debug
75 2023-07-02 19:22:03 [INFO ] main     test.pl:13 info
76 2023-07-02 19:22:03 [WARN ] main     test.pl:14 warn
77 2023-07-02 19:22:03 [ERROR] main     test.pl:15 error
78 ```
79