any control characters.
The first argument of `msg` can be OR'ed with additional flags. Most notably, you can
-add `L_SIGHANDLER` if you wish to log a message from a signal handler (calling
-time-related functions in libc from signal handlers is generally unsafe, so
-`msg` does not log a timestamp in such cases).
+add `L_SIGHANDLER` if you wish to log a message from a signal handler (see below
+for discussion on signals and reentrancy in general).
By default, all messages are logged to stderr. If you wish to use a log file,
call `log_file(@name)`. All subsequent logging will use this file and stderr
When no stream is explicitly selected, msg() uses the default stream, which
has registration number 0 and which is also returned by log_default_stream().
This stream has no explicit destination, but it can have substreams. (When
-a program starts, the default stream is connected to stderr; a call to log_file()
+a program starts, the default stream is connected to stderr. A call to log_file()
establishes a file logging stream and links it as the only substream of the
-default stream.)
+default stream. If you want to do that with any other log stream, call log_set_default_stream().)
Streams are reference-counted. When a stream is created, it gets reference count 1.
When it is linked as a substream of another stream, its reference count is incremented.
int main(int argc, char **argv)
{
log_init(argv[0]);
- struct log_stream *ls = log_new_file("/var/log/utterances");
+ struct log_stream *ls = log_new_file("/var/log/utterances", 0);
msg(L_INFO | ls->regnum, "Aye captain, we have a log file");
msg(L_INFO, "Alas, stderr still works");
return 0;
}
+Message types
+-------------
+Messages can also have types, which can be used for further filtering inside streams.
+By default, there is only the default message type. To obtain an identifier of a new
+type (again to be OR'ed to the log level when calling <<msg()>>), use <<log_register_type()>>.
+The number of types is currently limited to 32.
+
+If you want non-default types to be visible, enable the `LSFMT_TYPE` format flag.
+
Processes, threads and signals
------------------------------
When you fork a new process, it automatically inherits all currently configured log
streams. You should however call <<log_fork()>> to update the logger's notion
-of the current PID (at least when you use PID's in your log messages).
+of the current PID (at least when you use PID's in your log messages). Also, if you
+plan to exec() a process after fork(), do not forget to call <<log_close_all()>>,
+so that all file descriptors used for log files (except for stderr) are closed.
The <<basics:msg()>> function itself can be called from multiple threads in parallel
and it is atomic by design. The functions for setting up the logging machinery
you must use the `L_SIGHANDLER` flag to request it. Otherwise, deadlocks get
ready to happen.
+Messages logged with `L_SIGHANDLER` set are written directly to stderr (which
+is usually an alias for the main log file, at least if you use <<log_file()>>)
+and they do not carry a timestamp. Logging of sighandler messages to general
+log streams or to syslog is therefore not supported.
+
ucw/log.h
---------
!!ucw/log.h
+
+Limiting rate: ucw/tbf.h
+------------------------
+
+LibUCW also offers simple means of limiting the rate of log messages (or of any other
+events) by means of a so called 'Token Bucket Filter.' The idea behind this filter is
+simple: To log a message, we need a token. The available tokens are accumulated in
+a bucket which has a fixed 'filling rate' (the number of tokens arriving in the bucket
+per second, which may be a fractional number) and fixed 'maximum capacity.' The
+bucket receives the tokens continuously with the given rate and when it reaches
+the maximum capacity, the extra tokens are dropped on the floor. When a message
+has to be sent, we take a single token from the bucket and if there wasn't any,
+we drop the message.
+
+The filling rate therefore describes the maximum sustained rate of messages,
+while the bucket capacity tells the filter the maximum length of a short burst,
+which can temporarily exceed the rate.
+
+A general bucket filter is available in `ucw/tbf.h`. The usual way of using it
+to limit logging is to set up a filter hook of a stream which asks the TBF for
+every message. (Remember, though, that if your program is multithreaded, the
+filter hook can be run in multiple threads in parallel, so it has to guard the
+TBF by a lock.) The configuration interface for log streams described above
+is able to attach rate limiters to streams per user's request, so you usually
+need not take any extra care.
+
+!!ucw/tbf.h
projects / libucw.git / blobdiff