drama::logging::Logger Class Reference

Detailed Description

Implementation of a Class supporting Logging within an AAO DRAMA Task.

An object of this type is created automatically as part of the
creation of a DRAMA 2 drama::Task object. User code must invoke the open() method to actually open the log file. That can be
done in an action or the main line code. Access the logger using the drama::Task::RefTaskLogger() method.

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

It is assumed the machine time is set correctly.

The LOG_LEVEL action will be created if needed when the constructor is run (e.g. when the drama::Task object is created). The LOG_LEVEL parameter will be created if it does not exist

The Logger class Open() method 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. Open() will then set the LOG_LEVEL parameter to the actual logging level.

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

The log file is then opened. The directory for the log file is specified as the second argument to the open call, but if this is specified as a zero length string, the value of the DRAMA_LOGDIR environment variable is examined. If this is not defined, then the current default directory is chosen.

Within the directory, the name of the log file will be {taskname}-{date}.<ver>.log.[.gz] with the UT date in the format "YYYY-MM-DD". For the first file of the day, <ver> is set to "00". If the file already exists, <ver> is incremented until a name is found where no file yet exists.

On the first message on a UT new day, the log file will be closed and a new log file opened using the new date.

<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) exceeds 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 constructor), the log file is compressed as it is written using "gzip" run under "nice".
Normally a very high compression ratio is achieved. 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 suggests it is appropriate. When compress mode is enabled, SIGPIPE may be generated by a failure of the logger output commands (e.g. disk full). As a result, Logger will catch that signal and ignore it (A message is output to stderr). If the user application is using SIGPIPE is must set up its handler after calling the logging:Logger constructor (but I don't know how it can tell the difference between the Logger pipe failing or its own pipes failing).

The Logger tells DITS to use this class as its logging system, by calling DitsSetLogSys() - this will result in the logger being shutdown when DitsStop() is invoked or if another logging system is enabled. As a result of this feature.

Much logging is done internally by DRAMA. User code can call DitsLogMsg() or use the Logger::Log() method to log messages from application code which must be independent of the logging system being used.

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.

• COMMS Log DRAMA communications (sendings of messages etc).

• 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).

• DEBUG Log debugging messages

• DRAMA2 Log DRAMA 2 internals.

• USER1 User defined level 1. Equivalent to DitsLogMsg() DITS_LOG_USER1.

• USER2 User defined level 2. Equivalent to DitsLogMsg() DITS_LOG_USER2.

• USER3 User defined level 3.

• USER4 User defined level 4.

• ALL All levels are defined.

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

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.

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.

Note

The log file is compatible with GIT only if the environment variable DRAMA2_LOG_GIT_COMPATIBLE is defined.
If not, then an extra column giving the thread ID is written to the log file.

To ensure the DRAMA action context is correct, you should register any thread using DRAMA via the RegisterThread() methods. This is done automatically for drama::thread::TAction threaded action implementations and drama::thread::TUface thread UFACE methods. Only threads created by other means need to worry about registering themselves.

Older DRAMA task using GitLogger will not accept the value DRAMA2 in the DRAMA_LOG_LEVEL environment variable. As a result, we cannot always add DRAMA2 as a level to that environment variable. As a work-around, if this variable contains the value USER4, then DRAMA2 will also be set.

#include "logger.hh"

Public Member Functions
	Logger (Task *dramaTask)
	Construct a drama::logging::Logger object.
	~Logger ()
	Destructor.
void	Log (const IMP_AbsTime *time, unsigned level, bool nofmt, const char *prefix, const char *fmt,...)
	Log a message with a specified event time.
void	Log (unsigned level, bool nofmt, const char *prefix, const char *fmt,...)
	Log a message using C printf formating.
void	Open (const std::string &system, const std::string &dir="", bool compress=false)
	Open the log file.
void	RegisterThread (const Dits___CurActType &dramaContext, std::thread::id threadId=std::this_thread::get_id(), const char *func="*unnamed func*")
	Register the DRAMA context of a thread.
void	RegisterThread (std::thread::id sourceThread, std::thread::id newThread, const char *func="*unnamed func*")
	Register the DRAMA context of one thread against a new thread.
void	RegisterThread (std::thread::id threadId=std::this_thread::get_id(), const char *func="*unamed func*")
	Register the current DRAMA context against a thread.
void	RegisterThreadNoDramaCtx (std::weak_ptr< Task > dramaTask, const char *func="*non-drama*")
	Register this thread with with the logger, but without a DRAMA context.
void	Set (unsigned newLevels)
	Enable new logging levels.
template<typename... Types>
void	SLog (std::ostream &ostream, unsigned level, const std::string &prefix, const std::string &fmt, Types... args)
	Log a message using type safe formatting and output to a stream.
template<typename... Types>
void	SLog (unsigned level, const std::string &prefix, const std::string &fmt, Types... args)
	Log a message using type safe formatting.
void	Unset (unsigned disableLevels)
	Clear particular logging levels.

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

---

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

• logger.hh