logging.hpp

Go to the documentation of this file.

/**
 * \verbatim
 * ___    ___
 * \  \  /  /
 *  \  \/  /   Copyright (c) Fixposition AG (www.fixposition.com) and contributors
 *  /  /\  \   License: see the LICENSE file
 * /__/  \__\
 * \endverbatim
 *
 * @file
 * @brief Fixposition SDK: Logging
 *
 * @page FPSDK_COMMON_LOGGING Logging
 *
 * **API**: fpsdk_common/logging.hpp and fpsdk::common::logging
 *
 */
#ifndef __FPSDK_COMMON_LOGGING_HPP__
#define __FPSDK_COMMON_LOGGING_HPP__
 
/* LIBC/STL */
#include <cinttypes>  // PRI.. macros, often used with formats
#include <cstdarg>
#include <cstdint>
#include <sstream>
 
/* EXTERNAL */
 
/* PACKAGE */
#include "string.hpp"
#include "time.hpp"
 
namespace fpsdk {
namespace common {
/**
 * @brief Logging
 */
namespace logging {
/* ****************************************************************************************************************** */
 
/**
 * @name Printf() style logging
 *
 * For example: `INFO("Hello world, the number is %d", 42);`
 *
 * @{
 */
// clang-format off
/**
 * @brief Print a fatal message                                                                                         @hideinitializer
 */
#define FATAL(fmt, ...)   _FPSDK_LOGGING_LOG(FATAL,   "Fatal: "   fmt, ## __VA_ARGS__)
/**
 * @brief Print a error message                                                                                         @hideinitializer
 */
#define ERROR(fmt, ...)   _FPSDK_LOGGING_LOG(ERROR,   "Error: "   fmt, ## __VA_ARGS__)
/**
 * @brief Print a warning message                                                                                       @hideinitializer
 */
#define WARNING(fmt, ...) _FPSDK_LOGGING_LOG(WARNING, "Warning: " fmt, ## __VA_ARGS__)
/**
 * @brief Print a notice message                                                                                        @hideinitializer
 */
#define NOTICE(fmt, ...)  _FPSDK_LOGGING_LOG(NOTICE,              fmt, ## __VA_ARGS__)
/**
 * @brief Print a info message                                                                                          @hideinitializer
 */
#define INFO(fmt, ...)    _FPSDK_LOGGING_LOG(INFO,                fmt, ## __VA_ARGS__)
/**
 * @brief Print a debug message                                                                                         @hideinitializer
 */
#define DEBUG(fmt, ...)   _FPSDK_LOGGING_LOG(DEBUG,               fmt, ## __VA_ARGS__)
/**
 * @brief Print a debug hexdump                                                                                         @hideinitializer
 */
#define DEBUG_HEXDUMP(data, size, prefix, fmt, ...) _FPSDK_LOGGING_HEX(DEBUG, data, size, prefix, fmt, ## __VA_ARGS__)
#if !defined(NDEBUG) || defined(_DOXYGEN_) // Only for non-Release builds
 
/**
 * @brief Print a trace message (only debug builds, compiled out in release builds)                                     @hideinitializer
 */
#  define TRACE(fmt, ...) _FPSDK_LOGGING_LOG(TRACE,               fmt, ## __VA_ARGS__)
/**
 * @brief Print a trace hexdump (only debug builds, compiled out in release builds)                                     @hideinitializer
 */
#  define TRACE_HEXDUMP(data, size, prefix, fmt, ...) _FPSDK_LOGGING_HEX(TRACE, data, size, prefix, fmt, ## __VA_ARGS__)
#else
#  define TRACE(...)         /* nothing */
#  define TRACE_HEXDUMP(...) /* nothing */
#endif
 
/**
 * @brief Print a error message (throttled)                                                                             @hideinitializer
 */
#define ERROR_THR(millis, fmt, ...)   _FPSDK_LOGGING_THR(ERROR,   millis, fmt, ## __VA_ARGS__)
/**
 * @brief Print a warning message (throttled)                                                                           @hideinitializer
 */
#define WARNING_THR(millis, fmt, ...) _FPSDK_LOGGING_THR(WARNING, millis, fmt, ## __VA_ARGS__)
/**
 * @brief Print a notice message (throttled)                                                                            @hideinitializer
 */
#define NOTICE_THR(millis, fmt, ...)  _FPSDK_LOGGING_THR(NOTICE,  millis, fmt, ## __VA_ARGS__)
/**
 * @brief Print a info message (throttled)                                                                              @hideinitializer
 */
#define INFO_THR(millis, fmt, ...)    _FPSDK_LOGGING_THR(INFO,    millis, fmt, ## __VA_ARGS__)
/**
 * @brief Print a debug message (throttled)                                                                             @hideinitializer
 */
#define DEBUG_THR(millis, fmt, ...)   _FPSDK_LOGGING_THR(DEBUG,   millis, fmt, ## __VA_ARGS__)
// clang-format on
///@}
 
/**
 * @name C++ style logging
 *
 * For example, `INFO_S("Hello world, the number is " << 42);`
 *
 * @{
 */
// clang-format off
/**
 * @brief Print a fatal message                                                                                         @hideinitializer
 */
#define FATAL_S(expr)   _FPSDK_LOGGING_IF(FATAL,   std::stringstream ss; ss << expr; FATAL("%s", ss.str().c_str()))
/**
 * @brief Print a error message                                                                                         @hideinitializer
 */
#define ERROR_S(expr)   _FPSDK_LOGGING_IF(ERROR,   std::stringstream ss; ss << expr; ERROR("%s", ss.str().c_str()))
/**
 * @brief Print a warning message                                                                                       @hideinitializer
 */
#define WARNING_S(expr) _FPSDK_LOGGING_IF(WARNING, std::stringstream ss; ss << expr; WARNING("%s", ss.str().c_str()))
/**
 * @brief Print a debug message                                                                                         @hideinitializer
 */
#define DEBUG_S(expr)   _FPSDK_LOGGING_IF(DEBUG,   std::stringstream ss; ss << expr; DEBUG("%s", ss.str().c_str()))
/**
 * @brief Print a notice message                                                                                        @hideinitializer
 */
#define NOTICE_S(expr)  _FPSDK_LOGGING_IF(NOTIC,   std::stringstream ss; ss << expr; NOTICE("%s", ss.str().c_str()))
/**
 * @brief Print a info message                                                                                          @hideinitializer
 */
#define INFO_S(expr)    _FPSDK_LOGGING_IF(INFO,    std::stringstream ss; ss << expr; INFO("%s", ss.str().c_str()))
 
#if !defined(NDEBUG) || defined(_DOXYGEN_) // Only for non-Release builds
/**
 * @brief Print a trace message (only debug builds, compiled out in release builds)                                     @hideinitializer
 */
#  define TRACE_S(expr) _FPSDK_LOGGING_IF(TRACE,   std::stringstream ss; ss << expr; TRACE("%s", ss.str().c_str()))
#else
#  define TRACE_S(...) /* nothing */
#endif
// clang-format on
///@}
 
#if !defined(NDEBUG) || defined(_DOXYGEN_)  // Only for non-Release builds
//! Conditional compilation for non-Release builds
#  define IF_TRACE(...) __VA_ARGS__
#else
#  define IF_TRACE(...) /* nothing */
#endif
// Note: for other levels use LoggingIsLevel()
 
// ---------------------------------------------------------------------------------------------------------------------
 
/**
 * @brief Logging verbosity levels, default is INFO
 *
 * The logging levels loosely follow syslog levels (indicated in [] below, see also
 * https://en.wikipedia.org/wiki/Syslog)
 *
 * Libraries (fpsdk_common, fpsdk_ros1, ...) code shall only use WARNING and DEBUG.
 */
enum class LoggingLevel : int
{  // clang-format off
    FATAL    = 2,  //!< [2/crit]    Hard errors, critical conditions (for apps). Cannot be silenced.
    ERROR    = 3,  //!< [3/err]     Errors (for apps)
    WARNING  = 4,  //!< [4/warning] Warnings (for libs and apps)
    NOTICE   = 5,  //!< [5/notice]  Significant stuff, for example headings (for apps)
    INFO     = 6,  //!< [6/info]    Interesting stuff, the default level (for apps)
    DEBUG    = 7,  //!< [7/debug]   Debugging (for libs and apps)
    TRACE    = 8,  //!< [7/debug]   Extra debugging, only compiled-in in non-Release builds
};  // clang-format on
 
LoggingLevel& operator++(LoggingLevel& level);      //!< Increase verbosity (pre-increment)
LoggingLevel& operator--(LoggingLevel& level);      //!< Decrease verbosity (pre-decrement)
LoggingLevel operator++(LoggingLevel& level, int);  //!< Increase verbosity (post-increment)
LoggingLevel operator--(LoggingLevel& level, int);  //!< Decrease verbosity (post-decrement)
 
/**
 * @brief Stringify log level
 *
 * @param[in]  level  The logging level
 *
 * @returns a unique string identifying the level
 */
const char* LoggingLevelStr(const LoggingLevel level);
 
/**
 * @brief Check if given level would print
 *
 * @param[in]  level  The logging level in question
 *
 * @returns true if the given level would print, false otherwise
 */
bool LoggingIsLevel(const LoggingLevel level);
 
/**
 * @brief Logging "colours"
 */
enum class LoggingColour
{
    AUTO = 0,  //!< Automatic (default), use colours if stderr is an interactive terminal
    YES,       //!< Use colours (terminal escape sequences)
    NO,        //!< Do not use colours
    JOURNAL,   //!< Use systemd journal level indicators (instead of terminal colours), useful for systemd services
};
 
/**
 * @brief Stringify log level
 *
 * @param[in]  colour  The logging colour
 *
 * @returns a unique string identifying the level
 */
const char* LoggingColourStr(const LoggingColour colour);
 
/**
 * @brief Logging timestamps
 */
enum class LoggingTimestamps
{
    NONE = 0,  //!< No timestamps
    RELATIVE,  //!< Relative timestamps (since first logging message, sssss.sss format)
    ABSOLUTE,  //!< Absolute timestamps (local time, yyyy-mm-dd hh::mm:ss.sss format)
};
 
/**
 * @brief Stringify log level
 *
 * @param[in]  timestamps  The logging timestamps
 *
 * @returns a unique string identifying the level
 */
const char* LoggingTimestampsStr(const LoggingTimestamps timestamps);
 
struct LoggingParams;  // forward declaration
 
/**
 * @brief Custom logging print function signature
 */
using LoggingPrintFunc = void (*)(const LoggingParams&, const LoggingLevel, const char*);
 
/**
 * @brief Logging parameters
 */
struct LoggingParams
{
    /**
     * @brief Constructor
     *
     * @param[in]  level       Logging level
     * @param[in]  colour      Logging colours
     * @param[in]  timestamps  Logging timestamps
     */
    LoggingParams(const LoggingLevel level = LoggingLevel::INFO, const LoggingColour colour = LoggingColour::AUTO,
        const LoggingTimestamps timestamps = LoggingTimestamps::NONE);
    LoggingLevel level_;            //!< Logging level
    LoggingColour colour_;          //!< Level colours
    LoggingTimestamps timestamps_;  //!< Timestamps
    LoggingPrintFunc fn_;           //!< Custom logging print function
};
 
/**
 * @brief Configure logging
 *
 * @param[in]  params  Logging parameters
 *
 * Examples:
 *
 * @code{.cpp}
 * LoggingSetParams({ LoggingLevel::DEBUG });
 * LoggingSetParams({ LoggingLevel::DEBUG, LoggingColour::YES });
 * LoggingSetParams({ LoggingLevel::DEBUG, LoggingColour::AUTO, LoggingTimestamps::RELATIVE });
 * @endcode
 *
 * @returns a copy of the applied logging parameters
 */
LoggingParams LoggingSetParams(const LoggingParams& params);
 
/**
 * @brief Get current logging params
 *
 * @returns a copy of the current logging params
 */
LoggingParams LoggingGetParams();
 
/**
 * @brief Print a log message
 *
 * @note Use INFO(), DEBUG(), WARNING() etc. instead of this function.
 *
 * @param[in]  level  Logging level
 * @param[in]  fmt    printf() style format string
 * @param[in]  ...    arguments to the format string
 */
void LoggingPrint(const LoggingLevel level, const char* fmt, ...) PRINTF_ATTR(2);
 
/**
 * @brief Print a hexdump
 *
 * @note Typically, use DEBUG_HEXDUMP() or TRACE_HEXDUMP() instead of this function.
 *
 * @param[in]  level   Logging level
 * @param[in]  data    Pointer to start of data to dump
 * @param[in]  size    Size of data to dump
 * @param[in]  prefix  Prefix to add to each line, can be NULL to omit
 * @param[in]  fmt     printf() style format string (for a first line to print), can be NULL to omit
 * @param[in]  ...     Arguments to the format string
 */
void LoggingHexdump(const LoggingLevel level, const uint8_t* data, const std::size_t size, const char* prefix,
    const char* fmt, ...) PRINTF_ATTR(5);
 
// Helper macros
#ifndef _DOXYGEN_
#  define _FPSDK_LOGGING_LOG(_level_, _fmt_, ...) \
      ::fpsdk::common::logging::LoggingPrint(fpsdk::common::logging::LoggingLevel::_level_, _fmt_, ##__VA_ARGS__)
#  define _FPSDK_LOGGING_HEX(_level_, _data_, _size_, _prefix_, _fmt_, ...) \
      ::fpsdk::common::logging::LoggingHexdump(                             \
          fpsdk::common::logging::LoggingLevel::_level_, _data_, _size_, _prefix_, _fmt_, ##__VA_ARGS__)
#  define _FPSDK_LOGGING_IF(_level_, _code_)                                                         \
      if (::fpsdk::common::logging::LoggingIsLevel(fpsdk::common::logging::LoggingLevel::_level_)) { \
          _code_;                                                                                    \
      }
#  define _FPSDK_LOGGING_THR(_level_, _millis_, _fmt_, ...)          \
      do {                                                           \
          static uint32_t __last = 0;                                \
          const uint32_t __now = ::fpsdk::common::time::GetMillis(); \
          if ((__now - __last) >= (_millis_)) {                      \
              __last = __now;                                        \
              _level_(_fmt_, ##__VA_ARGS__);                         \
          }                                                          \
      } while (0)
#endif  // _DOXYGEN_
 
/* ****************************************************************************************************************** */
}  // namespace logging
}  // namespace common
}  // namespace fpsdk
#endif  // __FPSDK_COMMON_LOGGING_HPP__