DRAMA C++ Intro   Class Hierarchy   Alphabetical List of types   List of Classes   File List   Class Member Index   File Members Index   Related Pages  

GitLogger Class Reference

#include <gitlogger.h>

List of all members.


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.
Note:
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 GitActivate()). It may also be invoked in the tasks

 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.

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 DitsLogMsg() 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.


Public Methods

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

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

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

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.

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

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


Static Public Methods

void SetTimeOffset (long int t)
 Change the time offset.

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


Friends

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

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


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.

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 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::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::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.

void GitLogger::SetTimeOffset long int    t [inline, static]
 

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:

Click here for the DRAMA home page and here for the AAO home page.

For more information, contact tjf@aaoepp.aao.gov.au 

Generated on Tue Nov 3 09:09:56 2009 for AAO DRAMA C++ Interfaces by doxygen 1.2.18