summaryrefslogtreecommitdiff
path: root/doc/Logging.md
diff options
context:
space:
mode:
authorKargatum <dowlandtop@yandex.com>2021-04-17 16:20:07 +0700
committerGitHub <noreply@github.com>2021-04-17 11:20:07 +0200
commit4af4cbd3d966a05c584f4b6c63f69517dad0677d (patch)
tree1c4329a0c64233aaa033ac3788c1e4ddc9422eb9 /doc/Logging.md
parentb2861be1cd623182fd9e900c9ccfe8e063f28d8e (diff)
feat(Core/Logging): rework logging (#4692)
* feat(Core/Logging): rework logging * correct level for sql.sql * del unused config options * Correct build * correct after merge * whitespace 20:29:37 1. 'Player.cpp'. Replace (1) 20:29:37 2. 'ObjectMgr.cpp'. Replace (3) * 1 * correct logging * correct affter merge * 1 * 2 * LOG_LEVEL_WARN * #include "AppenderDB.h" * 3 * 4 * 5 * 1. 'WorldSocket.cpp'. Replace (1) * 6 * 1
Diffstat (limited to 'doc/Logging.md')
-rw-r--r--doc/Logging.md293
1 files changed, 293 insertions, 0 deletions
diff --git a/doc/Logging.md b/doc/Logging.md
new file mode 100644
index 0000000000..9059fd5756
--- /dev/null
+++ b/doc/Logging.md
@@ -0,0 +1,293 @@
+# Logging system "log4j-like"
+
+## LOGGERS AND APPENDERS
+
+```
+Logging system has two components: loggers and appenders. These types of
+components enable users to log messages according to message type and level and
+control at runtime where they are reported.
+```
+
+## 1. **LOGGERS**
+
+```
+The first and foremost advantage of this system resided in the ability to
+disable certain log statements while allowing others to print unhindered.
+This capability assumes that the loggers are categorized according to some
+developer-chosen criteria.
+```
+
+Loggers are named entitites. Logger names are case-sensitive and they follow
+the hierarchical naming rule:
+
+```
+A Logger is said to be an ancestor of another logger if its name followed
+by a dot is a prefix of the descendant logger name. A logger is salid to be
+a parent of a child logger if there are no ancestors between itself and the
+descendant logger.
+```
+
+For example, the logger named `"entities.player"` is a parent of the logger named
+`"entities.player.character"`. Similarly, `"entities"` is a parent of `"entities.player"`
+and an ancestor of `"entities.player.character"`.
+
+Loggers may be assigned levels. The set of possible levels are `TRACE`, `DEBUG`,
+`INFO`, `WARN`, `ERROR` AND `FATAL`, or be disabled using level `DISABLED`.
+
+By definition the printing method determines the level of a logging request.
+For example:
+
+```cpp
+LOG_INFO(...) // is a logging request of level INFO.
+```
+
+A logging request is said to be enabled if its level is less than or equal to
+the level of its logger. Otherwise, the request is said to be disabled. A logger
+without an assigned level will inherit one from the hierarchy
+
+Example
+
+```
+Logger Name Assigned Level Inherited Level
+root Proot Proot
+server None Proot
+```
+
+As `"server"` is not defined, it uses the root logger and it's log level.
+
+```
+FATAL < ERROR < WARN < INFO < DEBUG < TRACE
+```
+
+## 2. **APPENDERS**
+
+```
+The ability to selectively enable of dissable logging request based on their
+loggers is only part of the picture. This system allows logging requests to
+print to multiple destinations. An output destination is called an appender.
+Current system defines appenders for Console, files and Database, but can be
+easily extended to remote socket server, NT event loggers, syslog daemons or
+any other system.
+```
+
+More than one appender can be attached to one logger. Each enabled logging
+request for a given logger will be forwarded to all the appenders in that
+logger
+
+
+**CONFIGURATION**
+
+System will read all config elements with prefix `"Logger."` and `"Appender."`
+and configure the logging system. If `"root"` can not be properly configured the core
+will remove all loggers and appenders and create a default set:
+
+```
+- Logger "root" with log level Error
+- Logger "server" with log level Info
+- Appender "Console" to log to console
+```
+
+Appender config line follows the format:
+
+```
+Type,LogLevel,Flags,optional1,optional2
+```
+
+```
+Its a list of elements separated by comma where each element has its own meaning
+ Type: Type of the appender
+ 1 - (Console)
+ 2 - (File)
+ 3 - (DB)
+ LogLevel
+ 0 - (Disabled)
+ 1 - (Fatal)
+ 2 - (Error)
+ 3 - (Warning)
+ 4 - (Info)
+ 5 - (Debug)
+ 6 - (Trace)
+ Flags: Define some extra modifications to do to logging message
+ 1 - Prefix Timestamp to the text
+ 2 - Prefix Log Level to the text
+ 4 - Prefix Log Filter type to the text
+ 8 - Append timestamp to the log file name. Format: YYYY-MM-DD_HH-MM-SS
+ (Only used with Type = 2)
+ 16 - Make a backup of existing file before overwrite
+ (Only used with Mode = w)
+```
+
+Depending on the type, elements `optional1` and `optional2` will take different
+```
+ Colors (read as optional1 if Type = Console)
+ Format: "fatal error warn info debug trace"
+ 0 - BLACK
+ 1 - RED
+ 2 - GREEN
+ 3 - BROWN
+ 4 - BLUE
+ 5 - MAGENTA
+ 6 - CYAN
+ 7 - GREY
+ 8 - YELLOW
+ 9 - LRED
+ 10 - LGREEN
+ 11 - LBLUE
+ 12 - LMAGENTA
+ 13 - LCYAN
+ 14 - WHITE
+ Example: "1 9 3 6 5 8"
+
+ File: Name of the file (read as optional1 if Type = File)
+ Allows to use one "%u" to create dynamic files
+
+ Mode: Mode to open the file (read as optional2 if Type = File)
+ a - (Append)
+ w - (Overwrite)
+```
+
+Example:
+
+```
+Appender.Console1=1,5,6
+```
+
+Creates new appender to log to console any message with log level `DEBUG`
+or less and prefixes log type and level to the message.
+
+```ini
+Appender.Console2=1,2,1,"1 9 3 6 5 8"
+```
+
+Creates new appender to log to console any message with log level `ERROR`
+or less and prefixes timestamp to the message using colored text.
+
+```ini
+Appender.File=2,5,7,Auth.log,w
+```
+
+Creates new appender to log to file `"Auth.log"` any message with log level
+`DEBUG` or less and prefixes timestamp, type and level to message
+
+In the example, having two different loggers to log to console is perfectly
+legal but redundant.
+
+Once we have the list of loggers to read, system will try to configure a new
+logger from its config line. Logger config line follows the format:
+
+```ini
+LogLevel,AppenderList
+```
+
+Its a list of elements separated by comma where each element has its own meaning
+```
+ LogLevel
+ 0 - (Disabled)
+ 1 - (Fatal)
+ 2 - (Error)
+ 3 - (Warning)
+ 4 - (Info)
+ 5 - (Debug)
+ 6 - (Trace)
+ AppenderList: List of appenders linked to logger
+ (Using spaces as separator).
+```
+
+**EXAMPLES**
+
+1. **EXAMPLE 1**
+
+Log errors to console and a file called server.log that only contain
+logs for this server run. File should prefix timestamp, type and log level to
+the messages. Console should prefix type and log level.
+
+```ini
+Appender.Console=1,2,6
+Appender.Server=2,2,7,Server.log,w
+Logger.root=2,Console Server
+```
+
+Lets trace how system will log two different messages:
+
+```cpp
+LOG_ERROR("guild", "Guild 1 created");
+```
+
+System will try to find logger of type GUILD, as no logger is configured
+for GUILD it will use Root logger. As message Log Level is equal or less
+than the Log level of logger the message is sent to the Appenders
+configured in the Logger. `"Console"` and `"Server"`.
+
+Console will write:
+```
+"ERROR [GUILD] Guild 1 created"
+```
+
+Server will write to file
+```
+"2012-08-15 ERROR [GUILD] Guild 1 created"
+```
+
+```cpp
+LOG_INFO("entities.player.character", "Player Name Logged in");
+```
+
+System will try to find logger of type `"character"`, as no logger is
+configured for `"character"` it will use Root logger. As message Log Level is
+not equal or less than the Log level of logger the message its discarted.
+
+2. **EXAMPLE 2**
+
+Same example that above, but now i want to see all messages of level INFO on
+file and server file should add timestamp on creation.
+
+```ini
+Appender.Console=1,2,6
+Appender.Server=2,4,15,Server.log
+Logger.root=3,Console Server
+```
+
+Lets trace how system will log two different messages:
+```cpp
+LOG_ERROR("guild", "Guild 1 created");
+```
+
+Performs exactly as example 1.
+
+```cpp
+LOG_INFO("entities.player.character", "Player Name Logged in");
+```
+
+System will try to find logger of type `"character"`, as no logger is
+configured for `"character"` it will use Root logger. As message Log Level is
+equal or less than the Log level of logger the message is sent to the
+Appenders configured in the Logger. `"Console"` and `"Server"`.
+Console will discard msg as Log Level is not less or equal to this appender
+
+Server will write to file:
+```
+"2012-08-15 INFO [CHARACTER ] Player Name Logged in"
+```
+
+3. **EXAMPLE 3**
+
+As a dev, i may be interested in logging just a particular part of the core
+while i'm trying to fix something. So... i want to debug `"guild"` to maximum
+and also some `"character"` events to some point. Also im checking some Waypoints
+so i want SQLDEV to be logged to file without prefixes. All other messages
+should only be logged to console, `"guild"` to `TRACE` and `"character"` to `INFO`
+
+```ini
+Appender.Console=1,6
+Appender.SQLDev=2,5,0,SQLDev.log
+Logger.guild=6,Console
+Logger.entities.player.character=4,Console
+Logger.sql.dev=4,SQLDev
+```
+
+With this config, any message logger with a Log type different to `"guild"`,
+`"character"` or `"sql.dev"` will be ignored, as we didn't define a logger Root and
+system created a default Root disabled. Appender Console, log level should be
+defined to allow all possible messages of its loggers, in this case `"guild"` uses
+`TRACE (6)`, so Appender should allow it. Logger Characters will limit it's own
+messages to `INFO (4)`