1 # IRCNOW lib
2 
3 * 1. [Logger](#Logger)
4   * 1.1. [Formating the logger](#Formatingthelogger)
5   * 1.2. [SUGAR vs JSON](#SUGARvsJSON)
6   * 1.3. [Loggin Verbosity](#LogginVerbosity)
7 
8 
9 ##  1. <a name='Logger'></a>Logger
10 
11 Example usage:
12 ```perl
13 use strict;
14 use warnings;
15 
16 use lib qw(./lib);
17 use IRCNOW::Logger;
18 
19 my $logger = new IRCNOW::Logger(IRCNOW::Logger->INFO, IRCNOW::Logger->SUGAR);
20 #my $logger = new IRCNOW::Logger(IRCNOW::Logger->DEBUG, IRCNOW::Logger->SUGAR);
21 #my $logger = new Logger(IRCNOW::Logger->DEBUG, Logger->SUGAR, ":loglevel :timestamp :msg");
22 #my $logger = new Logger(IRCNOW::Logger->DEBUG, Logger->SUGAR, ":loglevel :invalid :timestamp :msg");
23 #my $logger = new Logger(IRCNOW::Logger->DEBUG, Logger->SUGAR, ":timestamp [:loglevel%2] :package%8 :file%10 :msg");
24 
25 $logger->debug("debug");
26 $logger->info("info");
27 $logger->warn("warn");
28 $logger->error("error");
29 
30 
31 # output:
32 # 2023-07-02 19:22:03 [DEBUG] main     test.pl:12 debug
33 # 2023-07-02 19:22:03 [INFO ] main     test.pl:13 info
34 # 2023-07-02 19:22:03 [WARN ] main     test.pl:14 warn
35 # 2023-07-02 19:22:03 [ERROR] main     test.pl:15 error
36 ```
37 
38 Arguments are: `verbosity, printType, format`.
39 
40 ###  1.1. <a name='Formatingthelogger'></a>Formating the logger
41 
42 Logger has these fields:
43 * timestamp
44 * loglevel
45 * package
46 * file
47 * fileline (file with line number)
48 * line
49 * msg
50 
51 Prepend the field with a `:` and postfix the field with a `%` followed by a number. Add spaces in between.
52 ex:
53 
54 `:timestamp [:loglevel%5] :package%8 :fileline%10 :msg`
55 
56 Note: If your field value is longer than the specified length, it will print out the full value.
57 EX: 
58 Format: `:timestamp [:loglevel%2] :package%8 :fileline%10 :msg` 
59 result:
60 ```
61 2023-07-02 19:21:54 [DEBUG] main     test.pl    debug
62 2023-07-02 19:21:54 [INFO] main     test.pl    info
63 2023-07-02 19:21:54 [WARN] main     test.pl    warn
64 2023-07-02 19:21:54 [ERROR] main     test.pl    error
65 ```
66 
67 ###  1.2. <a name='SUGARvsJSON'></a>SUGAR vs JSON
68 
69 There are two options to print logs:
70 * sugar
71 * JSON
72 
73 JSON logging is meant for being picked up by services such as grafana or the elk stack.
74 Sugar logging is meant for human readable output to stdout. 
75 
76 Example of JSON:
77 ```
78 { "level": "DEBUG", "msg": "debug", "package": "main", "file": "test.pl:12" }
79 { "level": "INFO", "msg": "info", "package": "main", "file": "test.pl:13" }
80 { "level": "WARN", "msg": "warn", "package": "main", "file": "test.pl:14" }
81 { "level": "ERROR", "msg": "error", "package": "main", "file": "test.pl:15" }
82 ```
83 
84 Example of Sugar:
85 ```
86 2023-07-02 19:22:03 [DEBUG] main     test.pl:12 debug
87 2023-07-02 19:22:03 [INFO ] main     test.pl:13 info
88 2023-07-02 19:22:03 [WARN ] main     test.pl:14 warn
89 2023-07-02 19:22:03 [ERROR] main     test.pl:15 error
90 ```
91 
92 ###  1.3. <a name='LogginVerbosity'></a>Logging Verbosity
93 
94 There are verbosity levels:
95 * NONE
96 * ERRORS
97 * ERROR (backwards compatible)
98 * WARNINGS
99 * WARN (backwards compatible)
100 * INFO
101 * DEBUG
102 * ALL
103 
104 Each level is in order such that if the `INFO` level was chosen, you would see logs for `ERROR`, `WARN`, and `INFO`