Logging#

This page documents the logging facilities for the Constellation C++ implementation.

Logging Macros#

The following macros should be used for any logging. They ensure proper evaluation of logging levels and additional conditions before the stream is evaluated.

Defines

LOG(...)#

Logs a message for a given level either to the default logger or a defined logger. The stream expression is only evaluated if logging should take place.

This macro takes either one or two arguments:

LOG(level) will log to the default logger of the framework
LOG(logger, level) will log to the chosen logger instance

logger is the optional constellation::log::Logger instance to use and level indicates the verbosity level on which to log.

LOG_IF(...)#

Logs a message if a given condition is true to either the default logger or a defined logger. The given condition is evaluated after it was determined if logging should take place based on the provided level.

This macro takes either two or three arguments:

LOG_IF(level, condition) will log to the default logger of the framework
LOG_IF(logger, level, condition) will log to the chosen logger instance

logger is the optional constellation::log::Logger instance to use, level indicates the verbosity level on which to log and condition represents the condition to be fulfilled before logging.

LOG_N(...)#

Logs a message at most N times either to the default logger or a defined logger.

This macro takes either two or three arguments:

LOG_N(level, count) will log to the default logger of the framework
LOG_N(logger, level, count) will log to the chosen logger instance

logger is the optional constellation::log::Logger instance to use, level indicates the verbosity level on which to log and count is the maximum number of times this message is logged.

LOG_ONCE(...)#

Logs a message at most one time either to the default logger or a defined logger. This macro is equivalent to LOG_N(…,1).

This macro takes either one or two arguments:

LOG_ONCE(level) will log to the default logger of the framework
LOG_ONCE(logger, level) will log to the chosen logger instance

logger is the optional constellation::log::Logger instance to use and level indicates the verbosity level on which to log.

LOG_NTH(...)#

Logs a message every Nth time the logging macro is called either to the default logger or a defined logger.

This macro takes either two or three arguments:

LOG_NTH(level, count) will log to the default logger of the framework
LOG_NTH(logger, level, count) will log to the chosen logger instance

logger is the optional constellation::log::Logger instance to use, level indicates the verbosity level on which to log and count is the interval of calls to the macro at which the message will be logged.

`constellation::log` Namespace#

enum class constellation::log::Level : int#

Log levels for the Constellation framework

The chosen values allows for direct casting to spdlog::level::level_enum and correspond to the levels defined in the CMDP protocol.

Values:

enumerator TRACE#: verbose information which allows to follow the call stack of the host program.

enumerator DEBUG#: information relevant to developers for debugging the host program.

enumerator INFO#: information on regular events intended for end users of the host program.

enumerator WARNING#: notify the end user of the host program of unexpected events which require further investigation.

enumerator STATUS#: communicate important information about the host program to the end user with low frequency.

enumerator CRITICAL#: notify the end user about critical events which require immediate attention and MAY have triggered an automated response by the host program or other hosts.

enumerator OFF#: no logging

spdlog::level::level_enum constellation::log::to_spdlog_level(Level level)#

Helper function to convert Constellation verbosity levels to spdlog::Level::level_enum values

Parameters:: level – Constellation verbosity level
Returns:: spdlog level value

Level constellation::log::from_spdlog_level(spdlog::level::level_enum level)#

Helper function to convert spdlog::Level::level_enum values to Constellation verbosity levels

Parameters:: level – spdlog level value
Returns:: Constellation verbosity constellation::log::Level

template<typename LevelL, typename LevelR> Level constellation::log::min_level(LevelL lhs, LevelR rhs)#

Compare two logging levels and return the lower one

Template Parameters:

LevelL – left logging level type
LevelR – right logging level type

Parameters:

lhs – Left logging level
rhs – Right logging level

Returns:

Minimum Constellation verbosity constellation::log::Level

class CMDPSink : public spdlog::sinks::base_sink<std::mutex>#

#include <constellation/core/log/CMDPSink.hpp>

Sink log messages via CMDP

Note that ZeroMQ sockets are not thread-safe, meaning that the sink requires a mutex.

Public Functions

CMDPSink(std::shared_ptr<zmq::context_t> context)#

Construct a new CMDPSink.

Parameters:: context – ZMQ context to be used

~CMDPSink() override#: Deconstruct the CMDPSink.

inline networking::Port getPort() const#

Get ephemeral port this logger sink is bound to.

Returns:: Port number

void enableSending(std::string sender_name)#

Set sender name and enable sending by starting the subscription thread.

Parameters:: sender_name – Canonical name of the sender

void sinkMetric(metrics::MetricValue metric_value)#

Sink metric

Parameters:: metric_value – Metric value to sink

Protected Functions

void sink_it_(const spdlog::details::log_msg &msg) final#

inline void flush_() final#

class Logger#

#include <constellation/core/log/Logger.hpp>

Logger class that to log messages via CMDP and to the console

This class implements a wrapper around the spdlog logger and provides additional features such as the possibility to perform logging using streams (with << syntax rather than enclosing the log message in parentheses)

Public Functions

Logger(std::string_view topic)#

Constructor a new logger.

Parameters:: topic – Topic of the logger (which is the name of the spdlog logger)

virtual ~Logger()#

inline bool shouldLog(Level level) const#

Check if a message should be logged given the currently configured log level.

Parameters:: level – Log level to be tested against the logger configuration
Returns:: Boolean indicating if the message should be logged

inline Level getLogLevel() const#

Return the current log level of the logger.

Note

This should not be used to determine if logging should take place, instead shouldLog() should be used

Returns:: Current log level

inline LogStream log(Level level, std::source_location src_loc = std::source_location::current()) const#

Log a message using a stream.

Parameters:

level – Log level of the log message
src_loc – Source code location from which the log message emitted

Returns:

LogStream to which the log message can be streamed

inline void log(Level level, std::string_view message, std::source_location src_loc = std::source_location::current()) const#

Log a message.

Parameters:

level – Level of the log message
message – Log message
src_loc – Source code location from which the log message emitted

void flush()#: Flush each spdlog sink (synchronously)

Public Static Functions

static Logger &getDefault()#: Return the default logger.

Protected Functions

inline Logger(std::shared_ptr<spdlog::async_logger> spdlog_logger)#

class LogStream : public std::ostringstream#

#include <constellation/core/log/Logger.hpp>

Log stream that executes logging upon its destruction

Public Functions

inline LogStream(const Logger &logger, Level level, std::source_location src_loc)#

inline ~LogStream() final#

class ProxySink : public spdlog::sinks::base_sink<std::mutex>#

#include <constellation/core/log/ProxySink.hpp>

Proxy sink for spdlog to define log level independent from global sink level

Public Functions

inline ProxySink(std::shared_ptr<spdlog::sinks::sink> sink)#

Construct a new proxy sink

Parameters:: sink – Shared pointer to sink for which to proxy

Protected Functions

inline void sink_it_(const spdlog::details::log_msg &msg) final#

inline void flush_() final#

class SinkManager#

#include <constellation/core/log/SinkManager.hpp>

Global sink manager.

This class manager the console and CMDP sinks and can creates new spdlog loggers.

Public Functions

~SinkManager() = default#

inline networking::Port getCMDPPort() const#

Get the ephemeral port to which the CMDP sink is bound to.

Returns:: Port number

void enableCMDPSending(std::string sender_name)#

Enable sending via CMDP.

Parameters:: sender_name – Canonical name of the satellite

inline void sendCMDPMetric(metrics::MetricValue metric_value)#

Send metric via the CMDP sink

Parameters:: metric_value – Metric value to sink

std::shared_ptr<spdlog::async_logger> getLogger(std::string_view topic)#

Get an asynchronous spdlog logger with a given topic.

This creates a new logger if no logger with the given topic exists

Parameters:: topic – Topic of the logger
Returns:: Shared pointer to the logger

inline std::shared_ptr<spdlog::async_logger> getDefaultLogger() const#: Return the default logger.

void setConsoleLevels(Level global_level, std::map<std::string, Level> topic_levels = {})#

Set the console log levels.

Parameters:

global_level – Global log level for console output
topic_levels – Log level overwrites for specific topics

void updateCMDPLevels(Level cmdp_global_level, std::map<std::string_view, Level> cmdp_sub_topic_levels = {})#

Update individual logger levels from CMDP subscriptions.

Parameters:

cmdp_global_level – Global subscription level
cmdp_sub_topic_levels – Map of individual logger subscription levels

Public Static Functions

static SinkManager &getInstance()#

Logging#

Logging Macros#

constellation::log Namespace#

`constellation::log` Namespace#