Public Member Functions | List of all members
ZDK::ILog Class Referenceabstract

Debug logging facility. More...

#include <ILog.h>

Inheritance diagram for ZDK::ILog:

Public Member Functions

virtual ZDK::Shared::Result LogOpen (ZDK::Shared::String fileName, ZDK::Shared::String oldFileName, ZDK::LoggingLevel maxLevel, intptr_t maxSizeBytes)=0
 Starts logging. More...
virtual void LogMessage (ZDK::LoggingLevel level, ZDK::LoggingFacility facility, ZDK::Shared::String facilityName, ZDK::Shared::String sourceFileName, int sourceLine, ZDK::Shared::String message)=0
 Log a message. More...
virtual ZDK::Shared::Result LogClose ()=0
 Stops logging. More...
virtual ZDK::Shared::ItemList< ZDK::LoggingFacility > ActiveFacilities () const =0
 Gets the list with all enabled logging facilities. More...
virtual void ActiveFacilities (ZDK::Shared::ItemList< ZDK::LoggingFacility > values)=0
 Configures the list with all enabled logging facilities. More...
virtual bool ShouldLogFacility (ZDK::LoggingFacility value) const =0
 Checks whether the given logging facility is enabled. More...
- Public Member Functions inherited from ZDK::IZHandle
virtual ZDK::ZDKHandle Handle () const =0
virtual operator ZDK::ZDKHandle () const =0
virtual void Initialize ()=0
virtual void ReleaseReference ()=0

Detailed Description

Debug logging facility.

Member Function Documentation

◆ ActiveFacilities() [1/2]

virtual ZDK::Shared::ItemList<ZDK::LoggingFacility> ZDK::ILog::ActiveFacilities ( ) const
pure virtual

Gets the list with all enabled logging facilities.

Debug log entries will be added only from the listed facilities.

The list with all active logging facilities
See also

◆ ActiveFacilities() [2/2]

virtual void ZDK::ILog::ActiveFacilities ( ZDK::Shared::ItemList< ZDK::LoggingFacility >  values)
pure virtual

Configures the list with all enabled logging facilities.

Debug log entries will be added only from the listed facilities.

[in]valueThe list with all active logging facilities
See also

◆ LogClose()

virtual ZDK::Shared::Result ZDK::ILog::LogClose ( )
pure virtual

Stops logging.

Closes the current log file, if open. Any further log requests, both internal and external, will do nothing.

Result of the closing
See also

◆ LogMessage()

virtual void ZDK::ILog::LogMessage ( ZDK::LoggingLevel  level,
ZDK::LoggingFacility  facility,
ZDK::Shared::String  facilityName,
ZDK::Shared::String  sourceFileName,
int  sourceLine,
ZDK::Shared::String  message 
pure virtual

Log a message.

Adds a log entry to the log.

The log format allows putting a "subsystem" in one of the log columns. The subsystem names are short uppercase only tags, optionally followed by a colon ':' and a snother short uppercase only tag signifying a sub-sub-system.

Custom subsystems used by the SDK user must follow the same rules to keep the log parsers simple.

Here is a (mostly complete) list of the tags in use:

RESIP:APP is used extensively in the library but will gradually be phased out in favor of WRAPPER WRAPPER is going to be used for the call managers RESIP (with the exception of :APP) is used by the SIP stack and some platform wrapper utilities ZRTP is the ZRTP implementation MSRP is the MSRP implementation

No parameters are optional.

[in]levelLog level. If it is higher than the current configured maximum log level the message will be ignored.
[in]facilityShort subsystem name in the form of TAG or TAG:SUBTAG
[in]facilityNameString representation of the subsystem
[in]sourceFileNameSource file name
[in]sourceLineSource file line
[in]messageThe log message itself

LoggingLevel, LoggingFacility, LogOpen()

◆ LogOpen()

virtual ZDK::Shared::Result ZDK::ILog::LogOpen ( ZDK::Shared::String  fileName,
ZDK::Shared::String  oldFileName,
ZDK::LoggingLevel  maxLevel,
intptr_t  maxSizeBytes 
pure virtual

Starts logging.

Starts the log facility. It will be used automatically by most library subsystems to log various events. If logging has already started it will be closed and reopened.

Can be called before StartContext() and/or after StopContext(). The log facility has its own life separate from the context.

The log files are always opened in append mode.

The logging facility will maintain up to two files and automatically rotate them. To enable rotation, set a non-zero maximum file size in "maxSizeBytes" and set the secondary log file name in "oldFileName". If "maxSizeBytes" or "oldFileName" are zero, rotation will be disabled.

The rotation consists of the following operations:

  1. The log file handle is closed.
  2. If the old file exists, it is removed.
  3. The log file is renamed.
  4. The log file handle is reopened.

Both file names MUST reside on the same logical file system.

All messages are first filtered by level. The "maxLevel" parameter sets the highest acceptable value, or in other words, the minimum severity level that will be logged. Confusingly, for legacy reasons, the lowest number has the highest severity.

The log format is CSV-like with the sequence " | " (space, pipe, space) as delimiter. The column count is fixed. All columns up to the last will not contain the pipe symbol but may contain white space. The last column is special, as it may contain unescaped pipe symbols and new lines, especially when the network stacks dump entire network messages.

Care must be taken when writing automated log parsers.

Here are the columns with example values:

  1. Log level (textual): DEBUG, INFO, ...
  2. Timestamp: 20160217-163725.551
  3. Subsystem tag: RESIP:APP, MSRP, WRAPPER, ...
  4. Thread id: 12204, 0xfefeb000
  5. Source file and line: audio_builder.cpp:93
  6. Log message: Unregister source= 0x80f3a4d0 ...
[in]fileNameMain log file name
[in]oldFileNameSecondary log file. Only used if "maxSizeBytes" is greater than 0.
[in]maxLevelMaximum level to log. Messages with higher level values, meaning lower severity are automatically dropped before filtering.
[in]maxSizeBytesMaximum size for a single log file. Affects both the main and the secondary file, resulting in maximum twice as much space used.
Result of the opening
See also
LoggingLevel, IResult

◆ ShouldLogFacility()

virtual bool ZDK::ILog::ShouldLogFacility ( ZDK::LoggingFacility  value) const
pure virtual

Checks whether the given logging facility is enabled.

[in]valueThe logging facility to be checked
See also

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