log (Logging)

Overview

C++ utilities for the log (Logging) module.

This module contains a class Logger which is used to gather log messages dispatched from different portions of an application into a single stream with a unified format. It wraps the C logging module, which provides the core of this functionality, in a convenience layer which can also spawn a background thread to handle large log volumes. See the documentation for the C module for more detailed information on the log format.

Generally a single instance per application is sufficient:

// This class handles the log messages gathered by the Logger class.
class MyLogHandler : public etcpal::LogMessageHandler
{
  etcpal::LogTimestamp GetLogTimestamp() override
  {
    // Grab a timestamp from the local system and return it
    // This function can also be omitted if you can't easily obtain system time. No timestamps
    // will be prepended to log messages in that case.
  }
 
  void HandleLogMessage(const EtcPalLogStrings& strings) override
  {
    // "strings" will contain strings pertaining to what action was requested by
    // Logger::SetLogAction().
 
    // Dispatch log messages in an application-defined way.
 
    // If human-readable logging is enabled, maybe...
    printf("%s\n", strings.human_readable);
    // If syslog is enabled, maybe...
    etcpal_sendto(my_syslog_socket, strings.syslog, strlen(strings.syslog), 0, &my_syslog_server);
  }
};
 
int main()
{
  etcpal_init(ETCPAL_FEATURE_LOGGING);
 
  MyLogHandler log_handler;
  etcpal::Logger logger;
 
  // Set parameters and start logging using the method-chaining setters:
  logger.SetLogMask(ETCPAL_LOG_UPTO(ETCPAL_LOG_INFO))
        .SetLogAction(kEtcPalLogCreateBoth)
        .SetSyslogFacility(ETCPAL_LOG_LOCAL1)
        .SetSyslogHostname(my_hostname)
        .SetSyslogAppName("My App")
        .SetSyslogProcId(0)
        .Startup(log_handler);
 
  // By default, a background thread is started to dispatch the log messages.
 
  logger.Log(ETCPAL_LOG_INFO, "Starting up!");
 
  // Use the shortcuts to log at a specific priority level:
 
  logger.Warning("Uh oh...");
  logger.Debug("We've reached line 250");
 
  // All log functions accept printf-style format specifiers and arguments
  logger.Info("This module has gone %d days without an accident", -1);
 
  // Use the log_params() getter to add logging output from other libraries with C APIs that
  // support it.
  somelib_init(&logger.log_params());
 
  // Shut down the logger when done to join the thread, if applicable.
  logger.Shutdown();
  etcpal_deinit(ETCPAL_FEATURE_LOGGING);
  return 0;
}

Data Structures
class	LogTimestamp
	An object representing the current local time with millisecond resolution for logging purposes. More...
class	LogMessageHandler
	An interface which handles log messages. More...
class	Logger
	A class for dispatching log messages. More...

Enumerations
enum class	LogDispatchPolicy { kDirect , kQueued }
	Options for the method by which the Logger dispatches log messages. More...

Enumeration Type Documentation

LogDispatchPolicy

enum LogDispatchPolicy

strong

Options for the method by which the Logger dispatches log messages.

Enumerator
kDirect	Log messages propagate directly from Log() calls to output streams (normally only used for testing)
kQueued	Log messages are queued and dispatched from another thread (recommended)