Differences

This shows you the differences between two versions of the page.

--- tools:logger:start [2017/02/03 11:15] – created graf
+++ tools:logger:start [2020/11/26 13:06] (current) – [Default LogWriter] ursgraf
@@ Line 1: / Line 1: @@
 ====== Logging ======
-The safety system is key to the EEROS framework. It regulates all interaction with the HAL (Hardware Abstraction Layer) and uses a safety level to determine the future course that the robot should take. If the situation becomes less safe, the robot may have its movement restricted to avoid damaging nearby people, materials, or itself.
+A logger enables a user to gather information about the state of the system at runtime. A logger can be declared and used as follows:
-All critical hardware inputs are read and all critical hardware outputs are driven by the safety system. So called //safety levels// exactly define in which state a robot can be. Such a level could be //initializing//, //homing// or //running//.
+<code cpp>
+  Logger::setDefaultStreamLogger(std::cout);
+  Logger log = Logger::getLogger();
+  log.info() << "Logger Test";
+  int a = 298;
+  log.warn() << "a = " << a;
+  log.error() << "first line" << endl << "second line";
+</code>
+A logger can log its output to one of several ''LogWriters''. Currently we support a ''StreamLogWriter'' which writes to the console and a ''SysLogWriter'' which writes into to system log file (on UNIX-Systems). \\
+While declaring a logger you can choose a category for it which is a single capital letter, see below:
+<code cpp>
+  Logger log1 = Logger::getLogger();      // no category
+  Logger log2 = Logger::getLogger('A');   // category 'A', log messages will show an 'A'
+</code>
-===== How it works =====
+===== Log Levels =====
-The most important function of the safety system is its run method. This method is called periodically by the executor. Here's how it works:
+A logger knows one of five severity levels.
+  * TRACE: lowest level
+  * INFO
+  * WARN
+  * ERROR
+  * FATAL: highest level
+Every ''Logger'' can be configured to pass only log messages which have a minimum severity level. This is accomplished with
 <code cpp>
-  void SafetySystem::run() {
+  log.show(LogLevel::WARN);
+</code>
+This would enable levels WARN, ERROR and FATAL. \\
+If you do not specify a certain level the default level is INFO. If you want to see all messages you have to use ''show(LogLevel::TRACE)'' or use the default ''show()'' which is also ''LogLevel::TRACE''.
-    // 1) Read inputs and check them
+===== Default LogWriter =====
-    for(auto ia : level->inputAction) {
+The EEROS library itself used several loggers, e.g. the safety system and the executor both log certain states and transitions. In order to see those generated messages it is necessary to specify a default ''LogWriter''. This default channel will take care of all the loggers in the library as well as user defined loggers, which do not have a specifically assigned ''LogWriter'' to it.
-      if(ia != nullptr) ia->check(&privateContext);
-    }
+<code cpp>
+  Logger::setDefaultStreamLogger(std::cout);
-    // 2) Execute level action
+  Logger log = Logger::getLogger();  // this logger will output onto the default ''LogWriter''.
-    if(level->action != nullptr) level->action(&privateContext);
-    // 3) Set outputs
-    for(auto oa : level->outputAction) {
-      if(oa != nullptr) oa->set();
-    }
-  }
 </code>
+If you forget to assign a default logger, you will not get logging information from components of the library such as the safety system or the executor.
+===== Logging into the Console and into a File  =====
+Sometimes it can be desirable to have a logger write to the console and write the same content into a file. This is especially helpful on a embedded system where you start an application remotely (e.g. through //ssh//). In such a case you can define a ''StreamLogWriter'' as follows:
+<code cpp>
+  Logger::setDefaultStreamLogger(std::cout, "/tmp/log");
+</code>
+A log file will be created at the given location. Its file name will be appended with the current date and time of the creation of the file.