System log
Circle uses a system log facility throughout the system to report status information from other system facilities or devices to the user. It is recommended to use this log facility from application code too and this is implemented in all Circle sample programs. While an application may write information messages directly to a device, the log facility provides additional services and is a standard tool for collecting status information in Circle. The system log is implemented by the class CLogger
.
CLogger
#include <circle/logger.h>
-
class CLogger
There is exactly one or no instance of CLogger
in the system. Only relatively simple programs can work without an instance of CLogger
.
Initialization
-
CLogger::CLogger(unsigned nLogLevel, CTimer *pTimer = 0, boolean bOverwriteOldest = TRUE)
Creates the instance of
CLogger
.nLogLevel
(0-4) determines, which log messages are included in the system log. Only messages with a log level smaller or equal tonLogLevel
are considered.pTimer
is a pointer to the system timer object. The time is not logged, ifpTimer
is zero. The following log levels are defined:
Level |
Severity |
Description |
---|---|---|
0 |
LogPanic |
Halt the system after processing this message |
1 |
LogError |
Severe error in this component, system may continue to work |
2 |
LogWarning |
Non-severe problem, component continues to work |
3 |
LogNotice |
Informative message, which is interesting for the system user |
4 |
LogDebug |
Message, which is only interesting for debugging this component |
Set
bOverwriteOldest
toFALSE
, if you want to keep old log messages forRead()
, even when the text ring buffer is full (see Read the log).
Write the log
Read the log
CLogger
has a 16K (LOGGER_BUFSIZE
) sized text ring buffer, which saves the written log messages. If this buffer is full, old messages will be overwritten by default. This behavior can be changed with the parameter bOverwriteOldest
of the constructor.
-
int CLogger::Read(void *pBuffer, unsigned nCount, boolean bClear = TRUE)
Reads and deletes maximal
nCount
characters from the log buffer. The read characters will be returned inpBuffer
. SetbClear
toTRUE
to remove the returned bytes from the buffer or toFALSE
to keep them. Returns the number of characters actually read.
-
boolean CLogger::ReadEvent(TLogSeverity *pSeverity, char *pSource, char *pMessage, time_t *pTime, unsigned *pHundredthTime, int *pTimeZone)
Returns the next log event (message) from a log event queue with maximal 50 entries or
FALSE
, if the queue is empty. The buffers atpSource
andpMessage
must have the sizesLOG_MAX_SOURCE
andLOG_MAX_MESSAGE
. This queue is normally used by the class CSysLogDaemon, which sends log messages to a syslog server.
Log event notification
-
void CLogger::RegisterEventNotificationHandler(TLogEventNotificationHandler *pHandler)
Registers a callback function, which is executed, when a log event (message) arrives. This is normally used by the class CSysLogDaemon, which sends log messages to a syslog server.
TLogEventNotificationHandler
has the following prototype:
void TLogEventNotificationHandler (void);
-
void CLogger::RegisterPanicHandler(TLogPanicHandler *pHandler)
Registers a callback function, which is executed, before a system halt, which is triggered by a log message with severity
LogPanic
. This is normally used by the class CSysLogDaemon, which sends log messages to a syslog server. IfCSysLogDaemon
is not in the system,RegisterPanicHandler()
can be used for other application purposes.TLogPanicHandler
has to following prototype:
void TLogPanicHandler (void);
Quick access
The following macros allow a quick access to the system log.
-
LOGMODULE(name)
Defines the C-string
name
as a name for this source module for generating log messages with the macros below.
-
LOGPANIC(format, ...)
-
LOGERR(format, ...)
-
LOGWARN(format, ...)
-
LOGNOTE(format, ...)
-
LOGDBG(format, ...)
Writes a message with the given severity,
format
and optional parameters to the system log using the module name defined withLOGMODULE()
.