doc/api/log.txt

   1 Old versions of ircu did not have very good means of dealing with
   2 logging.  In u2.10.11, an entirely new logging subsystem was written,
   3 allowing a server administrator much more power in determining what
   4 actions are to be logged where.  The new logging subsystem permits log
   5 messages to go to syslog, to a file, and to server operators via
   6 server notices, simultaneously (though having output to multiple log
   7 files is not presently supported).
   8
   9 All log messages have two values that are passed in with them: the
  10 logging level, which must be one of the values in enum LogLevel, and a
  11 logging subsystem, which must be one of the values in enum LogSys;
  12 these values are used as indexes into arrays within ircd_log.c, so be
  13 careful should you change them.
  14
  15 In addition to the LogLevel and LogSys, there is also a set of three
  16 flags that may be passed to the log_write() logging function; these
  17 flags may be used to suppress certain types of logging that may be
  18 undesirable.  For instance, when a server links, a log may be written
  19 containing the server's IP address; to prevent this IP address from
  20 ever showing up in a server notice, that invocation of log_write() is
  21 passed the LOG_NOSNOTICE flag.
  22
  23 <enum>
  24 enum LogLevel {
  25   L_CRIT,
  26   L_ERROR,
  27   L_WARNING,
  28   L_NOTICE,
  29   L_TRACE,
  30   L_INFO,
  31   L_DEBUG,
  32   L_LAST_LEVEL
  33 };
  34
  35 This enum describes the severity levels of a log message.  The
  36 severity decreases as you proceed downwards in the list, so L_DEBUG is
  37 less severe than L_INFO, and L_CRIT in the most severe of all.  The
  38 special value L_LAST_LEVEL should never be used; it merely marks the
  39 end of the list.
  40 </enum>
  41
  42 <enum>
  43 enum LogSys {
  44   LS_SYSTEM, LS_CONFIG, LS_OPERMODE, LS_GLINE, LS_JUPE, LS_WHO, LS_NETWORK,
  45   LS_OPERKILL, LS_SERVKILL, LS_USER, LS_OPER, LS_RESOLVER, LS_SOCKET,
  46   LS_DEBUG, LS_OLDLOG,
  47   LS_LAST_SYSTEM
  48 };
  49
  50 These are the various logging subsystems recognized by the logging
  51 subsystem.  Again, order is important, and again, LS_LAST_SYSTEM
  52 should never be used.
  53 </enum>
  54
  55 <function>
  56 void log_debug_init(int usetty);
  57
  58 This initializes the special-purpose debug logging code in the
  59 server.  If the _usetty_ parameter is non-zero, then all debugging
  60 output will go to the terminal regardless of file settings for the
  61 LS_DEBUG subsystem.  This function is not defined unless the server is
  62 compiled with -DDEBUGMODE.
  63 </function>
  64
  65 <function>
  66 void log_init(const char *process_name);
  67
  68 This initializes the entire logging subsystem, including special
  69 things such as storing the process name and opening syslog with the
  70 open_log() function.  It may only be called once.
  71 </function>
  72
  73 <function>
  74 void log_reopen(void);
  75
  76 All log files are persistently open, in order to avoid the overhead of
  77 re-opening the log file each time.  This function is used to close all
  78 the log files and to close and reopen syslog.  (Log files are opened
  79 again only when there is something to write to them.)
  80 </function>
  81
  82 <function>
  83 void log_close(void);
  84
  85 This closes all log files and the syslog prior to the server
  86 terminating.  Should logs need to be reopened after calling this
  87 function, call log_reopen() instead of log_init().
  88 </function>
  89
  90 <function>
  91 void log_write(enum LogSys subsys, enum LogLevel severity,
  92                unsigned int flags, const char *fmt, ...);
  93
  94 This is the actual logging function.  The _flags_ parameter is 0 or
  95 the bitwise OR of LOG_NOSYSLOG (suppresses syslogging), LOG_NOFILELOG
  96 (suppresses logging to a file) and LOG_NOSNOTICE (suppresses logging
  97 via server notices).  The _fmt_ parameter is a format string
  98 acceptable to ircd_snprintf(), which is the function called to
  99 actually format the log message.
 100 </function>
 101
 102 <function>
 103 void log_vwrite(enum LogSys subsys, enum LogLevel severity,
 104                 unsigned int flags, const char *fmt, va_list vl);
 105
 106 This is similar to log_write() except that it takes a va_list
 107 parameter.
 108 </function>
 109
 110 <function>
 111 char *log_cannon(const char *subsys);
 112
 113 This returns the canonical name for logging subsystem.  This probably
 114 should not be exposed here, but it is needed in ircd_features.c at
 115 present.
 116 </function>
 117
 118 <function>
 119 int log_set_file(const char *subsys, const char *filename);
 120
 121 This sets the file name for the specified logging subsystem to
 122 _filename_; returns 2 if the subsystem was undefined, 1 if the value
 123 of _filename_ was not understood, or 0 if there was no error.
 124 </function>
 125
 126 <function>
 127 char *log_get_file(const char *subsys);
 128
 129 This returns the current log file name for the given subsystem.
 130 </function>
 131
 132 <function>
 133 int log_set_facility(const char *subsys, const char *facility);
 134
 135 This sets the syslog facility for the specified logging subsystem to
 136 _facility_; returns 2 if the subsystem was undefined, 1 if the value
 137 of _facility_ was not understood, or 0 if there was no error.  Two
 138 special facility names may be given; "NONE" specifies that no
 139 syslogging should be performed, and "DEFAULT" specifies that ircd's
 140 default syslog facility should be used.
 141 </function>
 142
 143 <function>
 144 char *log_get_facility(const char *subsys);
 145
 146 This returns the current syslog facility for the given subsystem.  See
 147 the documentation for log_set_facility() for a description of the
 148 special facility names "NONE" and "DEFAULT."
 149 </function>
 150
 151 <function>
 152 int log_set_snomask(const char *subsys, const char *snomask);
 153
 154 This sets the server notice type for the specified logging subsystem
 155 to _snomask_; returns 2 if the subsystem was undefined, 1 if the value
 156 of _snomask_ was not understood, or 0 if there was no error.  The
 157 special server notice type "NONE" indicates that no server notices
 158 should be generated.  The other valid values for _snomask_ are:
 159 "OLDSNO," "SERVKILL," "OPERKILL," "HACK2," "HACK3," "UNAUTH,"
 160 "TCPCOMMON," "TOOMANY," "HACK4," "GLINE," "NETWORK," "IPMISMATCH,"
 161 "THROTTLE," "OLDREALOP," "CONNEXIT," and "DEBUG."
 162 </function>
 163
 164 <function>
 165 char *log_get_snomask(const char *subsys);
 166
 167 This returns the current server notice type for the given subsystem.
 168 See the documentation for log_set_snomask() for a description of the
 169 return values.
 170 </function>
 171
 172 <function>
 173 int log_set_level(const char *subsys, const char *level);
 174
 175 This function is used to set the minimum log level for a particular
 176 subsystem; returns 2 if the subsystem was undefined, 1 if the value of
 177 _level_ was not understood, or 0 if there was no error.  Any log
 178 notices generated with lower severity than that set with this function
 179 will not be logged.  Valid values are "CRIT," "ERROR," "WARNING,"
 180 "NOTICE," "TRACE," "INFO," and "DEBUG."
 181 </function>
 182
 183 <function>
 184 char *log_get_level(const char *subsys);
 185
 186 This returns the current minimum log level for the given subsystem.
 187 See the documentation for log_set_level() for a description of the
 188 return values.
 189 </function>
 190
 191 <function>
 192 int log_set_default(const char *facility);
 193
 194 This function sets the default syslog facility for all of ircd.  Valid
 195 values for _facility_ are as described for log_set_facility() with the
 196 exclusion of the "NONE" and "DEFAULT" facilities; returns 1 if the
 197 facility name was unrecognized (or proscribed) or 0 if there was no
 198 error.
 199 </function>
 200
 201 <function>
 202 char *log_get_default(void);
 203
 204 This simply returns ircd's default syslog facility.
 205 </function>
 206
 207 <function>
 208 void log_feature_unmark(void);
 209
 210 This function is called by the ircd_features.c subsystem and should
 211 not be called by any other part of ircd.  See the features API
 212 documentation for notes on what this function does.
 213 </function>
 214
 215 <function>
 216 void log_feature_mark(int flag);
 217
 218 This function is called by the ircd_features.c subsystem and should
 219 not be called by any other part of ircd.  See the features API
 220 documentation for notes on what this function does.
 221 </function>
 222
 223 <function>
 224 void log_feature_report(struct Client *to, int flag);
 225
 226 This function is called by the ircd_features.c subsystem and should
 227 not be called by any other part of ircd.  See the features API
 228 documentation for notes on what this function does.
 229 </function>
 230
 231 <authors>
 232 Kev <klmitch@mit.edu>
 233 </authors>
 234
 235 <changelog>
 236 [2001-06-13 Kev] Fix a minor typo.
 237
 238 [2000-12-18 Kev] Wrote some documentation on how to use the logging
 239 subsystem.
 240 </changelog>