Browse code

doc: reorganized the content of doc folder

Daniel-Constantin Mierla authored on 07/12/2016 13:54:42
Showing 1 changed files
1 1
new file mode 100644
... ...
@@ -0,0 +1,132 @@
1
+  _                      _                  _    ____ ___ 
2
+ | |    ___   __ _  __ _(_)_ __   __ _     / \  |  _ \_ _|
3
+ | |   / _ \ / _` |/ _` | | '_ \ / _` |   / _ \ | |_) | | 
4
+ | |__| (_) | (_| | (_| | | | | | (_| |  / ___ \|  __/| | 
5
+ |_____\___/ \__, |\__, |_|_| |_|\__, | /_/   \_\_|  |___|
6
+            |___/ |___/         |___/                    
7
+                         Ondrej Martinek <ondra@iptel.org>
8
+                                              January 2009
9
+
10
+This document contains the short description of the logging API in Kamailio
11
+for developers.
12
+
13
+Source files:
14
+    dprint.h
15
+    dprint.c
16
+
17
+ Compile-time control macros
18
+=============================
19
+
20
+    NO_LOG
21
+	If defined, logging is completely disabled in SER and no messages
22
+        are produced at all
23
+	       
24
+    NO_DEBUG
25
+	If defined, logging messages do not include the source filename and
26
+	line location info
27
+
28
+ Logging levels
29
+================
30
+
31
+    L_DBG   ... Debugging message (the lowest level)
32
+    L_INFO  ... Info message
33
+    L_WARN  ... Warning message
34
+    L_ERR   ... Error message
35
+    L_CRIT  ... Critical message
36
+    L_ALERT ... Alert message (the highest level)
37
+
38
+    The levels are implemented as integer macros.
39
+
40
+ Related variables
41
+===================
42
+
43
+    debug
44
+	The config.framework setting that contains the current logging level.
45
+	The initial value can be specified by "debug" parameter in ser.cfg or
46
+	by -d options on the command-line.  The default value is L_WARN.
47
+
48
+    log_stderror
49
+	The global variable which specifies whether the log messages should be
50
+	send to the standard error output or syslog (equals to zero).
51
+	Its value can be specified by "log_stderr" parameter in ser.cfg or
52
+	-E option on the command-line.
53
+	
54
+    log_facility
55
+	The config.framework setting that contains the current facility for
56
+	logging to syslog.
57
+	The initial value can be specified by "log_facility" parameter in
58
+	ser.cfg.  The default value is LOG_DAEMON.
59
+
60
+ Macro functions
61
+=================
62
+
63
+    * short macro aliases:
64
+	DBG(FMT, ARGS...)   alias for LOG(L_DBG, FMT, ARGS...)
65
+        INFO(FMT, ARGS...)  alias for LOG(L_INFO, FMT, ARGS...)
66
+        WARN(FMT, ARGS...)  alias for LOG(L_WARN, FMT, ARGS...)
67
+        ERR(FMT, ARGS...)   alias for LOG(L_ERR, FMT, ARGS...)
68
+        BUG(FMT, ARGS...)   alias for LOG(L_CRIT, FMT, ARGS...)
69
+        ALERT(FMT, ARGS...) alias for LOG(L_ALERT, FMT, ARGS...)
70
+
71
+    * LOG(LEVEL, FMT, ARGS...) macro
72
+	Prints the log message on stderr or syslog if the current debug level
73
+	is greater or equal to LEVEL.  The message has the following format:
74
+
75
+          - for messages by core:
76
+              PROC(PID) LEVEL: <core> [FILE:LINE]: MESSAGE
77
+
78
+          - for messages by modules:
79
+              PROC(PID) LEVEL: MODULE [FILE:LINE]: MESSAGE
80
+	      
81
+          - for messages by log(), xlog(), xdbg() script funcitons:
82
+              PROC(PID) LEVEL: <script>: MESSAGE
83
+
84
+	PROC is the SER process number and PID is the linux process ID.
85
+        LEVEL is one of "DEBUG", "INFO", "NOTICE", "WARNING", "ERROR",
86
+	"ALERT" and "BUG" strings.  MESSAGE is constructed from printf-like
87
+	arguments FMT and ARGS.
88
+
89
+        [FILE:LINE] location info is not present if NO_DEBUG macro is defined.
90
+  
91
+	Use of shorter aliases is preferred if LEVEL is a preprocess-time
92
+	constant.
93
+	
94
+    * LOG_(LEVEL, PREFIX, FMT, ARGS...) macro
95
+	Prints the log message on stderr or syslog if the current debug level
96
+	is greater or equal to LEVEL.  The message has the following format:
97
+	
98
+              PROC(PID) LEVEL: PREFIXMESSAGE
99
+
100
+	This is an internal macro try to avoid using it.
101
+
102
+
103
+--------------------------------------------------------------------------------
104
+
105
+ APPENDIX: Summary of the changes to the original API
106
+======================================================
107
+
108
+  - LOG(LEVEL, FMT, ARGS...) and the short macro corresponding to LEVEL level
109
+    made eqvivalent (eg. LOG(L_DBG, FMT, ARGS...) and DBG(FMT, ARGS...) prints
110
+    always the same message)
111
+
112
+  - changed the format of log messages produced by the macros to include
113
+    the log level, module name, filename, line (if applicable)
114
+     
115
+  - added new, internal LOG_(LEVEL, PREFIX, FORMAT, ARGS...) macro
116
+
117
+  - removed DPrint() and DEBUG() macros, L_DEFAULT log level and dprint()
118
+    function
119
+
120
+!!!
121
+!!! IMPORTANT! READ ME!
122
+!!!
123
+!!!  These changes (mainly the first two) require reformating of the most log
124
+!!!  messages in Kamailio core and module source files.  This step can be done
125
+!!!  automatically by running "scripts/logging/fix-logs-all" script BUT it
126
+!!!  was NOT originally performed because it would have generated too many
127
+!!!  changes in CVS which was discouraged by Andrei.  Instead, the developers
128
+!!!  are expected to run it when ready.
129
+!!!
130
+!!! IMPORTANT! READ ME!
131
+!!!  
132
+