AlexaClientSDK  3.0.0
A cross-platform, modular SDK for interacting with the Alexa Voice Service
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
alexaClientSDK::avsCommon::utils::logger::Logger Class Reference

#include <Logger.h>

Inheritance diagram for alexaClientSDK::avsCommon::utils::logger::Logger:
Inheritance graph
[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< Levelm_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:

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
levelThe 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
Anobserver 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]levelThe severity Level of this log line.
[in]timeThe time that the event to log occurred.
[in]threadMonikerMoniker of the thread that generated the event.
[in]textThe 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
configurationThe 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]levelThe severity Level to associate with this log entry.
[in]entryObject 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]levelThe severity Level to associate with this log entry.
[in]entryObject 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
Anobserver 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
levelThe 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]levelThe 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:

AlexaClientSDK 3.0.0 - Copyright 2016-2022 Amazon.com, Inc. or its affiliates. All Rights Reserved. Licensed under the Apache License, Version 2.0