Cpl::Logging Namespace Reference

The 'Logging' namespace provides a framework for Logging events. More...

Detailed Description

The 'Logging' namespace provides a framework for Logging events.

The framework provides the following features:

• The interface is thread safe.
• When an entry is logged it is timestamped. The application is required to provide the implementation of the time-stamp interface.
• Each entry 'logged' has a Category and Message Identifiers. The Category identifier is required to be globally unique to all logged items. The Message Identifiers are per Category (and are only unique within a Category)
• A Log entry contains the following:
  • Time-stamp
  • Category ID
  • Message ID
  • Text (interface uses printf semantics when creating a log entry)
• The framework is designed to allow/require the application provide the Category and Message identifiers/types.
• The logging framework supports selectively enabling/disabling logging by Category. Log entries for disabled Categories are silently discarded.
• Log entries are echoed to the CPL trace engine (when trace is enabled). The CategoryID text is used as the trace 'section'
• The framework supports caching log entries BEFORE the application's media.
• The application is responsible for storing log entries to a (presumably) persistent storage media. The logging framework dispatches each log entry to a thread-safe FIFO. It is the application's responsibility to consume the entries from the FIFO and record them in persistent storage. The FIFO supports change notifications via a model point - see Cpl::Containers::RingBufferMP.
  • The log entry data structure inherits from the Cpl::Persistent::Payload interface. The Payload interface defines two methods to serialize and deserialize the log entry data structure. While this introduces a dependency on the Cpl::Persistent namespace - the Payload interface definition has no other dependencies, i.e. the application is NOT required to use the Cpl::Persistent namespace for storing the log entry to persistent media.
• The log entry FIFO can overflow if the application is not storing log entries faster than the applicatoin is generating entries. When this happens, the framework discards log entries until space frees up in the queue. The framework tracks how many log entries where discarded and generates a special log entry with the details once there is space in the queue.

Classes
class	EntryData_T
	Defines the content of the Log entry. More...
class	LogSink
	This class is responsible for consuming the application's Log buffer and 'dispatching' log entries. More...

Functions
void	initialize (Cpl::Container::RingBufferMP< EntryData_T > &logEntryFIFO, uint32_t categoryIdForQueueOverflow, const char *categoryQueueOverflowText, uint16_t messageIdForQueueOverflow, const char *messageQueueOverflowText) noexcept
	This method is used to initialize the Logging framework.
void	shutdown () noexcept
	This method is used to shutdown/stop the Logging framework.
uint32_t	enableCategory (uint32_t categoryMask) noexcept
	This method is used to enable one or more log Categories.
uint32_t	disableCategory (uint32_t categoryMask) noexcept
	This method is used to disable one or more log Categories.
void	setCategoryMask (uint32_t newMask) noexcept
	This method is used to explicit set the category mask (i.e.
uint32_t	getCategoryEnabledMask () noexcept
	This method returns the current enabled/disabled Category mask.
template<class CATEGORY_ID , class MESSAGE_ID >
void	vlogf (CATEGORY_ID catId, MESSAGE_ID msgId, const char *msgTextFormat, va_list ap) noexcept
	This method is used to create log entry.
bool	getIDStrings (uint32_t categoryNumericValue, uint16_t messageIdNumericValue, Cpl::Text::String &dstCategoryString, Cpl::Text::String &dstMessageString) noexcept
	This method is implemented the application - it converts numeric values for the Category and Message IDs into text strings.
void	createAndAddLogEntry_ (uint32_t category, const char *catIdText, uint16_t msgId, const char *msgIdText, const char *format, va_list ap) noexcept
	This method is used to create the log entry and insert into the entry queue.
CplLoggingTime_T	now () noexcept
	This method returns the application current 'time' value that will be used to time-stamp each individual log entry.

Function Documentation

createAndAddLogEntry_()

void Cpl::Logging::createAndAddLogEntry_ ( uint32_t  category, const char *  catIdText, uint16_t  msgId, const char *  msgIdText, const char *  format, va_list  ap  )

noexcept

This method is used to create the log entry and insert into the entry queue.

disableCategory()

uint32_t Cpl::Logging::disableCategory ( uint32_t  categoryMask )

noexcept

This method is used to disable one or more log Categories.

Returns the previous enabled/disabled mask.

The method is thread safe

enableCategory()

uint32_t Cpl::Logging::enableCategory ( uint32_t  categoryMask )

noexcept

This method is used to enable one or more log Categories.

Returns the previous enabled/disabled mask.

Note: Upon initialization ALL categories are enabled

The method is thread safe

getCategoryEnabledMask()

uint32_t Cpl::Logging::getCategoryEnabledMask ( )

noexcept

This method returns the current enabled/disabled Category mask.

The method is thread safe

getIDStrings()

bool Cpl::Logging::getIDStrings ( uint32_t  categoryNumericValue, uint16_t  messageIdNumericValue, Cpl::Text::String &  dstCategoryString, Cpl::Text::String &  dstMessageString  )

noexcept

This method is implemented the application - it converts numeric values for the Category and Message IDs into text strings.

The method returns true when successful, else false is returned if one or more the input values are not 'valid'

Note: The output is only "as good" as the input, i.e. if the message IDs are not 'from' the category enum - the result will be indeterminate

initialize()

void Cpl::Logging::initialize ( Cpl::Container::RingBufferMP< EntryData_T > &  logEntryFIFO, uint32_t  categoryIdForQueueOverflow, const char *  categoryQueueOverflowText, uint16_t  messageIdForQueueOverflow, const char *  messageQueueOverflowText  )

noexcept

This method is used to initialize the Logging framework.

This method MUST be called BEFORE any 'logf' calls are made (i.e. call this method as early as possible in the application's startup-sequence).

now()

CplLoggingTime_T Cpl::Logging::now ( )

noexcept

This method returns the application current 'time' value that will be used to time-stamp each individual log entry.

The units of the value are application specific.

setCategoryMask()

void Cpl::Logging::setCategoryMask ( uint32_t  newMask )

noexcept

This method is used to explicit set the category mask (i.e.

the enable/ disable methods are OR/AND operations, this is assignment operation)

The method is thread safe

shutdown()

void Cpl::Logging::shutdown ( )

noexcept

This method is used to shutdown/stop the Logging framework.

This method should be called as part of orderly shutdown of the application.

vlogf()

template<class CATEGORY_ID , class MESSAGE_ID >

void Cpl::Logging::vlogf ( CATEGORY_ID  catId, MESSAGE_ID  msgId, const char *  msgTextFormat, va_list  ap  )

noexcept

This method is used to create log entry.

The method has printf() semantics. The method is thread safe.

This method is NOT intended to be called directly by the Application. The recommended paradigm is for the each Application to define it own set of Logging Categories and Message IDs. This include providing type-safe

NOTES:

• The CategoryId Enum must have an underlying integer type of: uint32_t
• A maximum of 32 symbols can be defined for the CategoryID
• Recommended that each CategoryID symbol must be less than 16 characters
• The MessageId Enums must have an underlying integer type of: uint16_t
• There is no limited (other than the BETTER_NUM limits) to number of message IDS.
• Recommended that each MessageID symbol must be less than 32 characters

Given:
    BETTER_ENUM( CategoryId, uint32_t
         , CRITICAL    = 0x00000001
         , WARNING     = 0x00000002
         , EVENT       = 0x00000004
         , ALARM       = 0x00000008
         , SECURITY    = 0x00000010
         , INFO        = 0x00000020
         , METRICS     = 0x00000040
         , LOGGER      = 0x00000080 );
 
    BETTER_ENUM( CriticalMsg, uint16_t, OUT_OF_MEMORY, BOB_HAPPENED, .... );
    BETTER_ENUM( WarningMsg, uint16_t, BATTERY_LOW, CONNECTION_DROPPED, .... );
    ...
 
    void logf( CriticalMsg msgId, const char* msgTextFormat, ... ) noexcept
    {
        va_list ap;
        va_start( ap, msgTextFormat );
        vlogf<CategoryId,CriticalMsg>( CategoryId::CRITICAL, msgId, msgTextFormat, ap );
        va_end( ap );
    }
 
    void logf( WarningMsg msgId, const char* msgTextFormat, ... ) noexcept
    {
        va_list ap;
        va_start( ap, msgTextFormat );
        vlogf<CategoryId,WarningMsg>( CategoryId::WARNING, msgId, msgTextFormat, ap );
        va_end( ap );
    }
 
    ...