Implementation of a Class supporting Logging with a DRAMA GIT Task. More...

#include <gitlogger.h>

Public Member Functions
	GitLogger (const char system, StatusType status, const char *dir=0, bool compress=false)
	Construct a GitLogger object. More...

void	CheckDayChange (int newDay, StatusType *status)
	Internal use only. More...

void	Log (unsigned level, bool nofmt, const char prefix, StatusType status, const char *fmt,...)
	Log a message. More...

void	Log (const IMP_AbsTime time, unsigned level, bool nofmt, const char prefix, StatusType status, const char fmt,...)
	Log a message with a specified event time. More...

void	Set (unsigned newFileLevels, unsigned newScreenLevels, StatusType *status)
	Enable new logging levels. More...

void	Unset (unsigned newFileLevels, unsigned newScreenLevels, StatusType *status)
	Clear existing logging levels. More...

Static Public Member Functions
static void	SetTimeOffset (long int t)
	Change the time offset. More...

static GitLogger *	GetLogger (StatusType *const status)
	Get the logger object. More...

Friends
void	GitLoggerFlushAlways (int flag, StatusType *status)
	C interface to setting the GitLogger flush flag. More...

FILE *	GitLoggerFile (StatusType *status)
	C interface to fetching the log file pointer. More...

void	GitLoggerTune (unsigned NewSettings, unsigned OldSettings, StatusType status)

Detailed Description

Implementation of a Class supporting Logging with a DRAMA GIT Task.

Simplified Usage:: An AAO style GIT task (using GitActivate() should invoke GitLoggerInit() as the first thing in its INITIALISE action and when re-initialising as part of its RESET action. Application code then can then DitsLogMsg() to log messages. DRAMA will also log various details via the logging system. Logging levels can be set using the {system}LOG_LEVEL environment variable or the LOG_LEVEL action, and default to logging of MsgOut messages and error messages/action completion in error. For use in non-GIT tasks, see below.

This class implements the GIT LOG_LEVEL action and routines which allow a DRAMA task to log. It also implements a DITS Logging system (see DitsSetLogSys()) which allows logging of internal DRAMA details.

Note: GitLogger must be on the heap so that it is cleaned up correctly when the task shutdowns. This is enforced by protecting the destructor.; It is assumed the machine time is set correctly. For VxWorks, this is not the case by default. Also, VxWorks does not support locales so the UT date may be used instead of the local date.

Discussions about the constructor  also refer to invoking of
the constructor by the C linkage routine GitLoggerInit().  See below.

The constructor may be invoked from a DRAMA action (normally 
INITIALISE/RESET
in an AAO task obeying the GIT specification (see@htmlonly <a href="../routines/GitActivate.html">GitActivate()</a>@endhtmlonly).  
It may also be invoked in the tasks@verbatim main()

function after DitsAppInit() but before DitsMainLoop() (or an equivalent) is invoked.

If you invoke the constructor from action code, then the LOG_LEVEL action must already exist as must the LOG_LEVEL parameter. The handler for that action will be changed, as will the action code.

If the action is invoked from outside a DRAMA action, then the LOG_LEVEL action will be created if needed. The LOG_LEVEL parameter will be created if it does not exist and the parameter system being used is Sdp (indicated by using DitsAppParamSys() to get the current parameter system details and finding SdpGet() is the getRoutine). If the parameter system has not been created, then it is created by calling SdpInit(). (Hence always call SdpInit() before invoking this routine if calling it yourself, otherwise there will be a memory leak and existing parameters will be lost).

Use must create objects of this class using "new" or invoke. GitLoggerInit(). When the new logging system is created, any old DITS logging system is deleted automaticaly by DITS, which invokes its logShutdown routine, which is also done when task shutdowns. The logShutdown routine of GitLogger will invoke "delete" on the object. Hence - you need not worry about deleting the object.

The GitLogger class constructor examines the LOG_LEVEL parameter and the {system_name}_LOG_LEVEL environment variable to determine the default logging levels. The parameter LOG_LEVEL must have the value NONE for the environment variable value to be used. The parameter will contain the actual value on return from the constructor.

If {system_name}_LOG_LEVEL does not exist, then DRAMA_LOG_LEVEL will be used and if that does nto exist then a default level of INST,ERROR,MSG is used.

The log file is then opened. The name is {taskname}-{date}.<ver>.log[.gz] with date in the format "DDMMMYYYY". This file is appended to if it already exists. The directory is specified as the third argument to the constructor, but if this is specified as 0 (the default) or a zero length string, the value of the DRAMA_LOGDIR environment variable is examined. If this is not defined, then the default directory is chosen. On the first message on a new day, the log file will be closed and a new log file opened. <ver> is the log file version number - this number starts are 00 and increased by 1 each time the log system is re-initialised or if the log file (when uncompressed) exceedes 1/2 a Giga-Byte in size. If compress mode is enabled, then the log file name has ".gz" appended after ".log"

If compress mode is enabled (See the contructor), the log file is compressed as it is written using "gzip" run under "nice". Normally a very high compression ratio is achivied. Note that running this way results in considerable buffering, as data is buffered by the gzip input and output streams to a very large extent. It is suggested that this mode only be used when the amount of data suggest it is appropiate. When compress mode is enabled, SIGPIPE may be generated by a failure of the logger output commands (e.g. disk full). As a result, GitLogger will catch that signal and ignore it (through a message it output to stderr). If the user application is using SIGPIPE is must set up its handler after calling the GitLogger constructor (but I don't know how it can tell the difference between the GitLogger pipe failing or its own pipes failing).

The GitLogger tells DITS to use this class as its logging system, by calling DitsSetLogSys() - this will also result in the object being deleted when DitsStop() is invoked or if another logging system is enabled. As a result of this feature, this object cannot be allocated globally, statically or on the stack. It must be created on the heap (using

new()

). To help enforce this, the destructor is made protected. Inheriting objects should have the same restriction.

Much logging is done internally by DRAMA. User code can call DitsLogMsg() or us the GitLoggers Log() method to log messages from application code.

The following logging levels are supported.

STARTUP Log startup messages. Equivalent to DitsLogMsg() DITS_LOG_STARTUP.

ERRORS Log errors - messages output by ERS and details of actions completing with bad status.

ACTENT Log action and uface entry. Used by DRAMA logging

ACTEXIT Log action and uface return. Used by DRAMA logging.

INST Log instrument specific functions. Equivalent to DitsLogMsg() DITS_LOG_INST.

   \arg COMMS    Log DRAMA communications (sendings of messages etc).

   \arg ARG      If logging action entry and/or action exit/comms, also 
                 log a string giving the details of any argument.  For 
                 comms logs, this is only arguments to a send (obey etc).

   \arg DEBUG    Log debugging messages

   \arg USER1    User defined level 1.  Equivalent to

DitsLogMsg() DITS_LOG_USER1.

   \arg  USER2    User defined level 2.  Equivalent to

DitsLogMsg() DITS_LOG_USER2.

\arg USER3 User defined level 3.

\arg USER4 User defined level 4.

\arg ALL All levels are defined.

GitLogger maintains an internal mask of the above levels. It or's this
if the level passed to it by the Log() routine and if the result
is non-zero the message is logged.

A second internal mask is kept which identifies logging messages
which are echoed to the screen. MsgOut messages always goto the
screen and you can change this effect for Ers message, which only
goto the screen if flushed.

The argument to the LOG_LEVEL action and the contents of the
environment variable/LOG_LEVEL parameter on startup should be a
comma or space separated list of the above names. If prefixed with
NO, the level is truned off, otherwise the level is turned on.

If the suffix -S is added to the name, we are indicating that screen
logging for this level should be turned on/off.

The LOG_LEVEL action without any arguments just returns (using MsgOut)
the current values. With or without an argument, the LOG_LEVEL
action causes the log file to be flushed to disk.

If you must use this from a C program, rather then a C++ program,
use the GitLoggerInit() routine to initialise the logger. Then
always use the@htmlonly <a href="../routines/DitsLogMsg.html">DitsLogMsg()</a>@endhtmlonly routine to log messages.

When possible (On VxWorks and on Unix machines with posix threads available)
GitLogger uses a low priority background thread to sync the log file to
disk every five seconds.

Constructor & Destructor Documentation

GitLogger::GitLogger	(	const char *	system,
		StatusType *	status,
		const char *	dir = `0`,
		bool	compress = `false`
	)

Construct a GitLogger object.

Creates a new log file and inserts GitLogger as the DRAMA logging system in the current DRAMA tasks. Note that DitsAppInit() must have already been invoked. See the class comments for full details.

Parameters

system	Logging system name - used to access environment variables
status	Modified status
dir	Directory into which to put the log file. If not supplied, use each $DRAMA_LOGDIR or default directory.
compress	If set true, then the log file is compressed automatically whilst it is being written. Defaults to false. This mode can be overwritten by setting the GIT_LOGGER_COMPRESS or GIT_LOGGER_NOCOMPRESS environment variables. The compressed file has .gz appended to the filename after .log.

Member Function Documentation

void GitLogger::CheckDayChange	(	int	newDay,
		StatusType *	status
	)

Internal use only.

static GitLogger* GitLogger::GetLogger ( StatusType *const status )

static

Get the logger object.

This static routine will return the address of the currently enabled logging object.

Parameters

status Modified status.

Returns: Null on failure with status set bad.

void GitLogger::Log	(	unsigned	level,
		bool	nofmt,
		const char *	prefix,
		StatusType *	status,
		const char *	fmt,
			...
	)

Log a message.

Explictly log a message

Parameters

level	The logging level. One of the LOG_ macro values
nofmt	If true, don't format the message, presume it is already formated.
prefix	A prefix to the log message, often indicting the function which makes the call.
status	Modified status.
fmt	C printf style format statement, unless nofmt is true.
...	If nofmt is false, then the arguments to the format.

void GitLogger::Log	(	const IMP_AbsTime *	time,
		unsigned	level,
		bool	nofmt,
		const char *	prefix,
		StatusType *	status,
		const char *	fmt,
			...
	)

Log a message with a specified event time.

Explictly log a message, but use the specified time rather then the current time. This allows a scheme which is buffering log messages to ensure the correct time is assoicated with the message.

You should be warned that this message will likely appear out of order with the normal log messages. You may need to sort your log file on the time fields to account for this. To help in identifing such lines - the colon (:) at the end of the time string is replaced by a plus sign (+).

Parameters

time	The time to associate with the log message. This is an IMP Time structure. You can use routines like ImpTimeNow() to construct these.
level	The logging level. One of the LOG_ macro values
nofmt	If true, don't format the message, presume it is already formated.
prefix	A prefix to the log message, often indicting the function which makes the call.
status	Modified status.
fmt	C printf style format statement, unless nofmt is true.
...	If nofmt is false, then the arguments to the format.

void GitLogger::Set	(	unsigned	newFileLevels,
		unsigned	newScreenLevels,
		StatusType *	status
	)

Enable new logging levels.

Parameters

newFileLevels	A mask of levels to enable for logging to the log file.
newScreenLevels	A mask of levels to enable for logging to the screen.
status	Modified status.

static void GitLogger::SetTimeOffset ( long int t )

inlinestatic

Change the time offset.

This is used in testing only - it allows an offset between the current system time and the time used by GitLogger to be specified, to allow testing of things such as the day change over code.

void GitLogger::Unset	(	unsigned	newFileLevels,
		unsigned	newScreenLevels,
		StatusType *	status
	)

Clear existing logging levels.

Parameters

newFileLevels	A mask of levels to disable for logging to the log file.
newScreenLevels	A mask of levels to disable for logging to the screen.
status	Modified status.

Friends And Related Function Documentation

FILE* GitLoggerFile ( StatusType * status )

friend

C interface to fetching the log file pointer.

This C interface returns the log file FILE pointer, allowing direct writes to the log file etc. Please use with care. Returns NULL if the file is not available (normally with status set bad).

void GitLoggerFlushAlways	(	int	flag,
		StatusType *	status
	)

friend

C interface to setting the GitLogger flush flag.

This C interface allows the flag which determines if the log file should be flushed after every write to be set. Set flag to true (non-zero) to enable this, false (0) to disable it

Depreciated: Use GitLoggerTune() instead.

The documentation for this class was generated from the following file:

gitlogger.h

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation