#include <Logger.h>

Inheritance diagram for alexaClientSDK::avsCommon::utils::logger::Logger:

[legend]

Public Member Functions
	Logger (Level level)

virtual	~Logger ()=default
	Destructor. More...

virtual void	setLevel (Level level)

bool	shouldLog (Level level) const

void	log (Level level, const LogEntry &entry)

void	logAtExit (Level level, const LogEntry &entry)

virtual void	emit (Level level, std::chrono::system_clock::time_point time, const char threadMoniker, const char text)

void	addLogLevelObserver (LogLevelObserverInterface *observer)

void	removeLogLevelObserver (LogLevelObserverInterface *observer)

Protected Member Functions
void	init (const configuration::ConfigurationNode configuration)

Protected Attributes
std::atomic< Level >	m_level
	The lowest severity level of logs to be output by this Logger. More...

Detailed Description

Logger provides an interface for capturing log entries as well as some core logging functionality. This includes:

Capturing the time, thread ID, and severity level to associate with each log entry.
Accessors for a logLevel value that specifies the minimum severity level of a log entries that will be emitted.
Initialization of logging parameters (so far just logLevel) from a ConfigurationNode.

The Logger interface is not typically used directly. Instead, calls to it are usually wrapped in invocations of macros. These macros provide a way to selectively compile out logging code. They also provide additional contextual information and direct logs to the appropriate Logger instance.

Typically, each .cpp source file using Logger defines a constant string and a macro near the top of the file. The constant string is typically named TAG. It specifies the name of the source of log entries originating from the file. This is usually the name of the class that is implemented in the file. The macro is typically named LX. It is used to create a LogEntry instance in-line with the expression that builds the text that is to be logged. The resulting LogEntry instance is passed to whatever instance of Logger is in use in the file. LX bakes in TAG to associate the log entry with its source. This macro also takes an argument that specifies the name of the event that is being logged. Both the constant string and event name are passed to the LogEntry constructor. Here is an example of the definitions that typically appear at the start of a .cpp file:

#define TAG "MyClass"
#define LX(event) alexaClientSDK::avsCommon::utils::logger::LogEntry(TAG, event)

When an event is to be logged, a wrapper macro named ACSDK_<LEVEL> is invoked with an expression that starts with an invocation of the LX macro. The value of <LEVEL> is the name of the LogLevel value to associate with the LogEntry. Here is an example of a very simple log line that logs a "somethingHappened" event from the source TAG with a severity level of INFO.

ACSDK_INFO(LX("somethingHappened"));

The LogEntry class has a builder style method that provides a convenient way to parameterize the event with named properties. This is done by adding zero or more LogEntry::d() method invocations after the LX() expression. The name of the property is always a string, and the value can be of any type for which an operator<<(std::ostream&, <type>) has been defined. These pairs are appended to the accumulating log string. Here is an example log line with two parameters:

ACSDK_WARN(LX("weirdnessHappened").d("<param1Name>", "stringValue").d("<param2Name>", 1 + 1 + 1);

The LogEntry class also has a rarely used m() method that can be used to add an optional free-form string at the end of the LogEntry. When present, this must be the last method appended to the expression. Here is an example of a log line with one parameter and a free-form message:

ACSDK_WARN(LX("weirdnessHappened").d("<param1Name>", "stringValue").m("free form text at the end");

The ACSDK_<LEVEL> macros allow logs to be selectively eliminated from the generated code. By default logs of severity DEBUG0 and above are included in DEBUG builds, and logs of severity INFO and above are in included in non DEBUG builds. These macros also perform an in-line logLevel check before evaluating the LX() expression. That allows much of the CPU overhead of compiled-in log lines to be selectively bypassed at run-time if the Logger's log level is set to not emit them.

Logging may also be configured on a per-module basis. Modules are defined by defining ACSDK_LOG_MODULE to a common name for all source files in a module. This name specifies the name of an object under configuration::ConfigurationNode::getRoot(). The named object contains configuration parameters for the per-module logger. So, for example, to set the logLevel of the foo module to WARN, the JSON used to configure the SDK would look something like this:

{
    "foo" : {
        "logLevel" : "WARN"
    }
    [... other propeties]
}

The value of ACSDK_LOG_MODULE is also used to generate a global inline function that is used to access the logger for that module. The signature of this function takes the form:

Logger& get<module name>Logger()

The value of ACSDK_LOG_MODULE is typically defined in the CMakeLists.txt for a module using the add_definitions() function. Here is an example defining the foo log module:

add_definitions("-DACSDK_LOG_MODULE=foo")

For modules that does not have the ACSDK_LOG_MODULE definition, logs will be defaulted to use the ConsoleLogger module Logger.

All logs (module specific or not) are output to a Sink Logger. By default, the Sink Logger is ConsoleLogger. The sink logger can be changed by calling initialize in LoggerSinkManager.

Constructor & Destructor Documentation

◆ Logger()

alexaClientSDK::avsCommon::utils::logger::Logger::Logger ( Level level )

Logger constructor.

Parameters

level The lowest severity level of logs to be emitted by this Logger.

◆ ~Logger()

virtual alexaClientSDK::avsCommon::utils::logger::Logger::~Logger ( )

virtualdefault

Destructor.

Member Function Documentation

◆ addLogLevelObserver()

void alexaClientSDK::avsCommon::utils::logger::Logger::addLogLevelObserver ( LogLevelObserverInterface * observer )

Add an observer to this object.

Parameters

An	observer to this class, which will be notified when the logLevel changes.

◆ emit()

virtual void alexaClientSDK::avsCommon::utils::logger::Logger::emit	(	Level	level,
		std::chrono::system_clock::time_point	time,
		const char *	threadMoniker,
		const char *	text
	)

virtual

Emit a log entry. Default implementation is no-op. NOTE: This method must be thread-safe. NOTE: Delays in returning from this method may hold up calls to Logger::log().

Parameters

[in]	level	The severity Level of this log line.
[in]	time	The time that the event to log occurred.
[in]	threadMoniker	Moniker of the thread that generated the event.
[in]	text	The text of the entry to log.

Reimplemented in alexaClientSDK::avsCommon::utils::logger::test::TestLogger, alexaClientSDK::sampleApplications::common::ConsolePrinter, alexaClientSDK::sampleApplications::ipcServerSampleApp::ConsolePrinter, alexaClientSDK::avsCommon::utils::logger::ConsoleLogger, alexaClientSDK::avsCommon::utils::logger::ModuleLogger, and alexaClientSDK::applicationUtilities::androidUtilities::AndroidLogger.

◆ init()

void alexaClientSDK::avsCommon::utils::logger::Logger::init ( const configuration::ConfigurationNode configuration )

protected

Initialize Logger parameters from the specified ConfigurationNode.

Parameters

configuration The ConfigurationNode to read Logger parameters from.

◆ log()

void alexaClientSDK::avsCommon::utils::logger::Logger::log	(	Level	level,
		const LogEntry &	entry
	)

Send a log entry to this Logger.

Parameters

[in]	level	The severity Level to associate with this log entry.
[in]	entry	Object used to build the text of this log entry.

◆ logAtExit()

void alexaClientSDK::avsCommon::utils::logger::Logger::logAtExit	(	Level	level,
		const LogEntry &	entry
	)

Send a log entry to this Logger while program is exiting.

Use this method if the code may be run while destroying a static object. This method should not rely in any other static object.

Note: The user code should still ensure that the Logger object itself is valid.

Parameters

[in]	level	The severity Level to associate with this log entry.
[in]	entry	Object used to build the text of this log entry.

◆ removeLogLevelObserver()

void alexaClientSDK::avsCommon::utils::logger::Logger::removeLogLevelObserver ( LogLevelObserverInterface * observer )

Remove an observer to this object.

Parameters

An	observer to this class that will be removed from the notification of logLevel changes.

◆ setLevel()

virtual void alexaClientSDK::avsCommon::utils::logger::Logger::setLevel ( Level level )

virtual

Set the lowest severity level to be output by this logger.

Parameters

level The lowest severity level to be output by this logger.

Reimplemented in alexaClientSDK::avsCommon::utils::logger::ModuleLogger.

◆ shouldLog()

bool alexaClientSDK::avsCommon::utils::logger::Logger::shouldLog ( Level level ) const

inline

Return true of logs of a specified severity should be emitted by this Logger.

Parameters

[in] level The Level to check.

Returns: Returns true if logs of the specified Level should be emitted.

Member Data Documentation

◆ m_level

std::atomic<Level> alexaClientSDK::avsCommon::utils::logger::Logger::m_level

protected

The lowest severity level of logs to be output by this Logger.

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

/workplace/avs-device-sdk/AVSCommon/Utils/include/AVSCommon/Utils/Logger/Logger.h

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Logger()

◆ ~Logger()

Member Function Documentation

◆ addLogLevelObserver()

◆ emit()

◆ init()

◆ log()

◆ logAtExit()

◆ removeLogLevelObserver()

◆ setLevel()

◆ shouldLog()

Member Data Documentation

◆ m_level