Logging

Overview

Logging is the process of printing useful information to a console or file that can be used for later analysis or forensics. Logging is especially useful for debugging problems that occurred during an execution of a MADARA-enabled program. In this wiki, we'll describe how to use madara::logger::Logger and some of the helpful features.

Input basics and behavior

The inputs are an integer for level, and a printf like string along with required parameters defined by the input string. The level is optional, as it can be set via a setter method. However, the logging output can be prefixed with custom printf like keystrings. Further, the input print like string also supports these custom Madara keystrings. Supporting functional methods define how to work with the logger class. Thread local methods are listed elsewhere. Specialized thread local methods are shown in the Thread Local section.

clear(void) -- Clears all log targets
set_level (int level) -- Sets the maximum logging detail level
int get_level (void) -- Gets the maximum logging detail level
void add_term (void) -- Adds terminal (often stdin, stderr, etc) to logger outputs that is OS specific
void add_syslog (void) -- Add logger output to the OS's syslog
std::string get_tag (void) -- Returns tag used for the syslog
void set_tag (const std::string & tag) -- Set the tag used for the syslog
void add_file (const std::string & filename) -- Set the file to write logger output.

The approach used allows to write to various terminals and multiple log files, while filtering using a "level."

Another technical point is that there is only a single static logger instance, so it can be used at large in the system. However, see the Thread Local section to understand how thread specific information can be used.

Example use case of logging in Madara

#include "madara/logger/GlobalLogger.h"
#include "madara/utility/Utility.h"

namespace logger = madara::logger;
namespace utility = madara::utility;

int main (int, char **)
{
  logger::global_logger.get()->set_timestamp_format("%x %X: ");
  logger::global_logger->set_level (logger::LOG_DETAILED);
  logger::global_logger->clear ();
  logger::global_logger->add_file ("test_logging_to_file.txt");

  logger::global_logger->add_term ();
  loggering.log (logger::LOG_ERROR,"This is a %s with level %d!\n","test",
                  logger::global_logger->get_level());
  return 0;
}

Build the test program.

somelinux:~.$/a.out 2>&1 tmp.out
somelinux:~$cat tmp.out
09/15/18 12:17:55: This is a test with level 3!

somelinux:~$cat test_logging_to_file.txt
09/15/18 12:17:55: This is a test with level 3!

Logging level

Logging level is meant to filter out log messages and prioritize certain log messages to be recorded. The current type of levels range from tracing, errors, major/minor, and warning etc. By default, the log level is -1 which is off. If the level is set to >= 0, then the logging is done to match the assigned level. The level can be overriden by logging method params and thread local logging levels.

      LOG_EMERGENCY  LOG_ALWAYS   LOG_ERROR
      LOG_WARNING    LOG_MAJOR    LOG_MINOR
      LOG_TRACE      LOG_DETAILED LOG_MADARA_MAX

Timestamp output prefix

Each logging output line is prefixed and customizable via a strftime format. Proprietary keystrings were added for thread local purposes, otherwise refer to the man pages for strftime.

#include "madara/logger/GlobalLogger.h"
#include "madara/utility/Utility.h"

namespace logger = madara::logger;
namespace utility = madara::utility;

int main (int, char **)
{
  logger::global_logger.get()->set_timestamp_format("%x %X: ");
  logger::global_logger->set_level (logger::LOG_DETAILED);

  int lvl = logger::global_logger.get()->get_level();
  madara_logger_ptr_log (logger::global_logger.get(),logger::LOG_ALWAYS,
                         "This is a test %d",lvl);

  logger::global_logger.get()->set_timestamp_format("%x %X Your Prop data: ");
  madara_logger_ptr_log (logger::global_logger.get(),logger::LOG_ALWAYS,
                         "CounterThread::Run MTZ: %MTZ This is a test %d\n",lvl);
}

Build the test program.

somelinux:~.$/a.out > tmp.out
somelinux:~$cat tmp.out
09/15/18 13:00:56: This is a test 3
09/15/18 13:00:56 Your Prop data: This is a test 3

Thread Local

In order to provide better contextual information with threads, additional information is stored and avilable in the logging class.

%MGT - ulong - Get current time in seconds (only avail in as logging param).
%MTN - std::string - Thread name
%MTZ - double - Hertz value

These value are also available as public methods in the current running thread.
* std::string get_thread_name(void)            -- return thread name
* void set_thread_name(const std::string name) -- set thread name
* double get_thread_hertz(void)                -- get thread hertz value
* void set_thread_hertz(double hertz)          -- set thread hertz value

#include "madara/logger/GlobalLogger.h"
#include "madara/utility/Utility.h"

namespace logger = madara::logger;
namespace utility = madara::utility;

void function()
{
  logger::global_logger.get()->set_thread_hertz(333.0);
  logger::global_logger.get()->set_timestamp_format("%x %X %MTZ %MGT (%MTN): ");
  logger::global_logger->set_level (logger::LOG_DETAILED);

  int lvl = logger::global_logger.get()->get_level();
  madara_logger_ptr_log (logger::global_logger.get(),logger::LOG_ALWAYS,
                         "These are proprietary values for local thread %MTZ %MGT (%MTN)\n");
}

Build the test program.

somelinux:~.$/a.out
               
09/15/18 14:02:18 333 16911.836141 (thread0): These are proprietary values for local thread 333 16911.836141 (thread0)

~~~ 
----

## Video Tutorials

[First Steps in MADARA](http://www.youtube.com/watch?v=TS3y1a3yX1E&list=PL2htjCHh_RcxB7ehL96pTjOm6xbOOpy5J&index=1): Covers installation and a Hello World program.\
[Intro to Networking](http://www.youtube.com/watch?v=kThUlBxzIQw&list=PL2htjCHh_RcxB7ehL96pTjOm6xbOOpy5J&index=2): Covers creating a multicast transport and coordination and image sharing between multiple agents.

----

<b>C++ Guide Series</b>\
[Architecture](MadaraArchitecture) | Knowledge Base | [Networking](InteractingWithTheTransport) | [Containers](KnowledgeContainers) | [Threads](WorkingWithThreads) | [Optimizations](OptimizingKaRL) | [KaRL](KarlLanguage) | [Encryption](Encryption) | [Checkpointing](Checkpointing) | [Knowledge Performance](KnowledgePerformance)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly