Logger: Allow adding custom sinks

(example in logger/loggerTest.cxx, docs in fairmq/docs/Logging.md)

examples/common/mcstack/FairStack.cxx

@@ -358,7 +358,7 @@ void FairStack::Print(Option_t*) const
   LOG(info) << "FairStack: Number of primaries        = " << fNPrimaries;
   LOG(info) << "              Total number of particles  = " << fNParticles;
   LOG(info) << "              Number of tracks in output = " << fNTracks;
-  if (gLogger->IsLogNeeded(fair::Logger::Severity::DEBUG1)) {
+  if (gLogger->IsLogNeeded(fair::Severity::DEBUG1)) {
     for (Int_t iTrack=0; iTrack<fNTracks; iTrack++) {
       (static_cast<FairMCTrack*>( fTracks->At(iTrack))->Print(iTrack));
     }

fairmq/README.md

@@ -12,12 +12,18 @@ Standard FairRoot is running all the different analysis tasks within one process
       1. [Ownership](docs/Transport.md#211-ownership)
    2. [Channel](docs/Transport.md#22-channel)
    3. [Poller](docs/Transport.md#23-poller)
-3. [Configuration](docs/Configuration.md#1-configuration)
+3. [Configuration](docs/Configuration.md#3-configuration)
     1. [Device Configuration](docs/Configuration.md#31-device-configuration)
     2. [Communication Channels Configuration](docs/Configuration.md#32-communication-channels-configuration)
         1. [JSON Parser](docs/Configuration.md#321-json-parser)
         2. [SuboptParser](docs/Configuration.md#322-suboptparser)
     3. [Introspection](docs/Configuration.md#33-introspection)
-4. [Development](docs/Development.md#3-development)
-   1. [Testing](docs/Development.md#31-testing)
-5. [Examples](docs/Examples.md#4-examples)
+4. [Development](docs/Development.md#4-development)
+   1. [Testing](docs/Development.md#41-testing)
+5. [Logging](docs/Logging.md#5-logging)
+   1. [Log severity](docs/Logging.md#51-log-severity)
+   2. [Log verbosity](docs/Logging.md#52-log-verbosity)
+   3. [Color for console output](docs/Logging.md#53-color)
+   4. [File output](docs/Logging.md#54-file-output)
+   5. [Custom sinks](docs/Logging.md#55-custom-sinks)
+6. [Examples](docs/Examples.md#6-examples)

fairmq/docs/Development.md

@@ -1,8 +1,8 @@
 ← [Back](../README.md)
 
-# 3. Development
+# 4. Development
 
-# 3.1 Testing
+## 4.1 Testing
 
 For unit testing it is often not feasible to boot up a full-blown distributed system with dozens of processes.
 

fairmq/docs/Examples.md

@@ -1,6 +1,6 @@
 ← [Back](../README.md)
 
-# 4. Examples
+# 6. Examples
 
 A collection of simple examples in `FairRoot/examples/MQ` directory demonstrates some common usage patterns of FairMQ.
 

fairmq/docs/Logging.md

@@ -0,0 +1,99 @@
+← [Back](../README.md)
+
+# 5. Logging
+
+The FairMQLogger header uses fair::Logger library for logging.
+
+All log calls go through the provided LOG(severity) macro. Output through this macro is thread-safe. Logging is done to cout, file output and/or custom sinks.
+
+## 5.1 Log severity
+
+The log severity is controlled via:
+```C++
+fair::Logger::SetConsoleSeverity("<severity level>");
+// and/or
+fair::Logger::SetFileSeverity("<severity level>");
+// and/or
+fair::Logger::SetCustomSeverity("<customSinkName>", "<severity level>");
+```
+
+where severity level is one of the following:
+
+```C++
+"nolog",
+"fatal",
+"error",
+"warn",
+"state",
+"info",
+"debug",
+"debug1",
+"debug2",
+"debug3",
+"debug4",
+"trace",
+```
+
+Logger will log the chosen severity and all above it (except "nolog", which deactivates logging for that sink completely). Fatal severity is always logged.
+
+When running a FairMQ device, the log severity can be simply provided via `--severity <level>` cmd option.
+
+## 5.2 Log verbosity
+
+The log severity is controlled via:
+```C++
+fair::Logget::SetVerbosity("<verbosity level>");
+```
+
+it is same for all sinks, and is one of the follwing values: `low`, `medium`, `high`, `veryhigh`, which translates to following output:
+
+```
+low:      [severity] message
+medium:   [HH:MM:SS][severity] message
+high:     [process name][HH:MM:SS:µS][severity] message
+veryhigh: [process name][HH:MM:SS:µS][severity][file:line:function] message
+```
+
+When running a FairMQ device, the log severity can be simply provided via `--verbosity <level>` cmd option.
+
+## 5.3 Color
+
+Colored output on console can be activated with:
+```C++
+Logger::SetConsoleColor(true);
+```
+
+## 5.4 File output
+
+Output to file can be enabled via:
+```C++
+Logger::InitFileSink("<severity level>", "test_log", true);
+```
+which will add output to "test_log" filename (if third parameter is `true` it will add timestamp to the file name) with `<severity level>` severity.
+
+## 5.5 Custom sinks
+
+Custom sinks can be added via `Logger::AddCustomSink("sink name", "<severity>", callback)` method.
+
+Here is an example adding a custom sink for all severities ("trace" and above). It has access to the log content and meta data. Custom log calls are also thread-safe.
+
+```C++
+    Logger::AddCustomSink("MyCustomSink", "trace", [](const string& content, const LogMetaData& metadata)
+    {
+        cout << "content: " << content << endl;
+
+        cout << "available metadata: " << endl;
+        cout << "std::time_t timestamp: " << metadata.timestamp << endl;
+        cout << "std::chrono::microseconds us: " << metadata.us.count() << endl;
+        cout << "std::string process_name: " << metadata.process_name << endl;
+        cout << "std::string file: " << metadata.file << endl;
+        cout << "std::string line: " << metadata.line << endl;
+        cout << "std::string func: " << metadata.func << endl;
+        cout << "std::string severity_name: " << metadata.severity_name << endl;
+        cout << "fair::Severity severity: " << static_cast<int>(metadata.severity) << endl;
+    });
+```
+
+If only output from custom sinks is desirable, console/file sinks must be deactivated by setting their severity to `"nolog"`.
+
+← [Back](../README.md)

fairtools/FairLogger.cxx

@@ -49,99 +49,99 @@ void FairLogger::Fatal(const char* file, const char* line, const char* func, con
 {
     va_list ap;
     va_start(ap, format);
-    Log(fair::Logger::Severity::fatal, file, line, func, format, ap);
+    Log(fair::Severity::fatal, file, line, func, format, ap);
     va_end(ap);
 }
 
 void FairLogger::Error(const char* file, const char* line, const char* func, const char* format, ...)
 {
-    if (IsLogNeeded(fair::Logger::Severity::error))
+    if (IsLogNeeded(fair::Severity::error))
     {
         va_list ap;
         va_start(ap, format);
-        Log(fair::Logger::Severity::error, file, line, func, format, ap);
+        Log(fair::Severity::error, file, line, func, format, ap);
         va_end(ap);
     }
 }
 
 void FairLogger::Warning(const char* file, const char* line, const char* func, const char* format, ...)
 {
-    if (IsLogNeeded(fair::Logger::Severity::warning))
+    if (IsLogNeeded(fair::Severity::warning))
     {
         va_list ap;
         va_start(ap, format);
-        Log(fair::Logger::Severity::warning, file, line, func, format, ap);
+        Log(fair::Severity::warning, file, line, func, format, ap);
         va_end(ap);
     }
 }
 
 void FairLogger::Info(const char* file, const char* line, const char* func, const char* format, ...)
 {
-    if (IsLogNeeded(fair::Logger::Severity::info))
+    if (IsLogNeeded(fair::Severity::info))
     {
         va_list ap;
         va_start(ap, format);
-        Log(fair::Logger::Severity::info, file, line, func, format, ap);
+        Log(fair::Severity::info, file, line, func, format, ap);
         va_end(ap);
     }
 }
 
 void FairLogger::Debug(const char* file, const char* line, const char* func, const char* format, ...)
 {
-    if (IsLogNeeded(fair::Logger::Severity::debug))
+    if (IsLogNeeded(fair::Severity::debug))
     {
         va_list ap;
         va_start(ap, format);
-        Log(fair::Logger::Severity::debug, file, line, func, format, ap);
+        Log(fair::Severity::debug, file, line, func, format, ap);
         va_end(ap);
     }
 }
 
 void FairLogger::Debug1(const char* file, const char* line, const char* func, const char* format, ...)
 {
-    if (IsLogNeeded(fair::Logger::Severity::debug1))
+    if (IsLogNeeded(fair::Severity::debug1))
     {
         va_list ap;
         va_start(ap, format);
-        Log(fair::Logger::Severity::debug1, file, line, func, format, ap);
+        Log(fair::Severity::debug1, file, line, func, format, ap);
         va_end(ap);
     }
 }
 
 void FairLogger::Debug2(const char* file, const char* line, const char* func, const char* format, ...)
 {
-    if (IsLogNeeded(fair::Logger::Severity::debug2))
+    if (IsLogNeeded(fair::Severity::debug2))
     {
         va_list ap;
         va_start(ap, format);
-        Log(fair::Logger::Severity::debug2, file, line, func, format, ap);
+        Log(fair::Severity::debug2, file, line, func, format, ap);
         va_end(ap);
     }
 }
 
 void FairLogger::Debug3(const char* file, const char* line, const char* func, const char* format, ...)
 {
-    if (IsLogNeeded(fair::Logger::Severity::debug3))
+    if (IsLogNeeded(fair::Severity::debug3))
     {
         va_list ap;
         va_start(ap, format);
-        Log(fair::Logger::Severity::debug3, file, line, func, format, ap);
+        Log(fair::Severity::debug3, file, line, func, format, ap);
         va_end(ap);
     }
 }
 
 void FairLogger::Debug4(const char* file, const char* line, const char* func, const char* format, ...)
 {
-    if (IsLogNeeded(fair::Logger::Severity::debug4))
+    if (IsLogNeeded(fair::Severity::debug4))
     {
         va_list ap;
         va_start(ap, format);
-        Log(fair::Logger::Severity::debug4, file, line, func, format, ap);
+        Log(fair::Severity::debug4, file, line, func, format, ap);
         va_end(ap);
     }
 }
 
-void FairLogger::Log(fair::Logger::Severity severity, const char* file, const char* line, const char* func, const char* format, va_list arglist)
+void FairLogger::Log(fair::Severity severity, const char* file, const char* line, const char* func, const char* format, va_list arglist)
 {
     // If the format string together with the argument list was used once it can't
     // be used another time. Don't know why but if we do so the arguments are not
@@ -175,7 +175,7 @@ void FairLogger::Log(fair::Logger::Severity severity, const char* file, const ch
     }
 }
 
-bool FairLogger::IsLogNeeded(fair::Logger::Severity severity)
+bool FairLogger::IsLogNeeded(fair::Severity severity)
 {
     return fair::Logger::Logging(severity);
 }

fairtools/FairLogger.h

@@ -40,7 +40,7 @@ class FairLogger
         }
         else
         {
-            fair::Logger::SetConsoleSeverity(fair::Logger::Severity::fatal);
+            fair::Logger::SetConsoleSeverity(fair::Severity::fatal);
         }
     }
 
@@ -58,7 +58,7 @@ class FairLogger
         }
         else
         {
-            fair::Logger::SetFileSeverity(fair::Logger::Severity::fatal);
+            fair::Logger::SetFileSeverity(fair::Severity::fatal);
         }
     }
 
@@ -84,7 +84,7 @@ class FairLogger
         fair::Logger::SetVerbosity(verbosity);
     }
 
-    bool IsLogNeeded(fair::Logger::Severity severity);
+    bool IsLogNeeded(fair::Severity severity);
 
     void Fatal  (const char* file, const char* line, const char* func, const char* format, ...)  __attribute__((deprecated("Use 'LOG(severity) << content;' macro interface instead.")));
     void Error  (const char* file, const char* line, const char* func, const char* format, ...)  __attribute__((deprecated("Use 'LOG(severity) << content;' macro interface instead.")));
@@ -112,7 +112,7 @@ class FairLogger
 
     ~FairLogger() {}
 
-    void Log(fair::Logger::Severity level, const char* file, const char* line, const char*, const char* format, va_list arglist);
+    void Log(fair::Severity level, const char* file, const char* line, const char*, const char* format, va_list arglist);
 
     static void LogFatalMessage();