Integrate logger with library

Initialize logger with a silent mode and output set to stderr.

Allow for setting loggers for loader and adapters separately with
options passed as environment variables UR_LOG_* (append adapter
name or null for null adapter):
UR_LOG_LOADER="level:info;flush:warning;output:stdout"
UR_LOG_NULL="level:debug;output:file,<file_path>"

Where:
- `level` is the level determining minimum log level to be printed,
  possible values: debug, info, warning, error (default: no messages)
- `flush` is the log level at which all the messages will be printed
  immediately (default: error)
- `output` is the stream to which messages will be printed, possible
  values: stdout, stderr, file (default: stderr)

Author: PatKamin

scripts/core/INTRO.rst

@@ -195,11 +195,58 @@ Unified Runtime loader implements tracing support through the `XPTI framework <h
        | **user_data**: A pointer to `function_with_args_t` object, that includes function ID, name, arguments, and return value.
      - None
 
+Logging
+---------------------
+
+Logging in UR is handled by loggers which can be set for each library separately. There are several levels of logging: *debug*, *info*, *warning*, and *error*.
+The level of logging determines what messages will be printed, ie. the level set to *warning* means all messages at levels *warning* and *error* will be printed.
+By default, no messages are printed.
+
+By default, there is a guarantee that *error* messages are flushed immediately. One can change this behavior to flush on lower-level messages.
+
+Loggers redirect messages to *stdout*, *stderr*, or a file (default: *stderr*).
+
+All of these logging options can be set with **UR_LOG_LOADER** and **UR_LOG_NULL** environment variables described in the **Environment Variables** section below.
+Both of these environment variables have the same syntax for setting logger options::
+
+  "[level:debug|info|warning|error];[flush:<debug|info|warning|error>];[output:stdout|stderr|file,<path>]"
+  
+  * level - a log level, meaning that only messages from this level and above are printed,
+            possible values, from the lowest level to the highest one: *debug*, *info*, *warning*, *error*,
+  * flush - a flush level, meaning that messages at this level and above are guaranteed to be flushed immediately,
+            possible values are the same as above,
+  * output - indicates where messages should be printed,
+             possible values are: *stdout*, *stderr* and *file*,
+             when providing a *file* output option, a *<path>* is required
+
+  .. note::
+    For output to file, a path to the file have to be provided after a comma, like in the example above. The path has to exist, file will be created if not existing. 
+    All these three logger options are optional. The defaults are set when options are not provided in the environment variable.
+    Options have to be separated with `;`, option names, and their values with `:`. Additionally, when providing *file* output, the keyword *file* and a path to a file
+    have to be separated by `,`.
+
+An example of an environment variable for setting up the loader library logger with logging level set to *info*, flush level set to *warning*, and output set to
+the `out.log` file::
+
+  UR_LOG_LOADER="level:info;flush:warning;output:file,out.log"
+
+An example of an environment variable for setting up the null adapter library with logging level set to *warning* and output set to stdout::
+
+  UR_LOG_NULL="level:warning;output:stdout"
+
 Environment Variables
 ---------------------
 
 Specific environment variables can be set to control the behavior of unified runtime or enable certain features.
 
+.. envvar:: UR_LOG_LOADER
+
+   Holds parameters for setting Unified Runtime loader logging. The syntax is described in the **Logging** section above.
+
+.. envvar:: UR_LOG_NULL
+
+   Holds parameters for setting Unified Runtime null adapter logging. The syntax is described in the **Logging** section above.
+
 .. envvar:: UR_ADAPTERS_FORCE_LOAD
 
    Holds a comma-separated list of library names used by the loader for adapter discovery. By setting this value you can

source/common/logger/ur_level.hpp

@@ -4,6 +4,9 @@
 #ifndef UR_LEVEL_HPP
 #define UR_LEVEL_HPP 1
 
+#include <stdexcept>
+#include <string>
+
 namespace logger {
 
 enum class Level { DEBUG,
@@ -27,6 +30,29 @@ inline constexpr auto level_to_str(Level level) {
     }
 }
 
+inline auto str_to_level(std::string name) {
+    struct lvl_name {
+        std::string name;
+        Level lvl;
+    };
+
+    const lvl_name lvl_names[] = {{"debug", Level::DEBUG},
+                                  {"info", Level::INFO},
+                                  {"warning", Level::WARN},
+                                  {"error", Level::WARN}};
+
+    for (auto const &item : lvl_names) {
+        if (item.name.compare(name) == 0) {
+            return item.lvl;
+        }
+    }
+    throw std::invalid_argument(
+        std::string("Parsing error: no valid log level for string '") + name +
+        std::string("'.") +
+        std::string(
+            "\nValid log level names are: debug, info, warning and error"));
+}
+
 } // namespace logger
 
 #endif /* UR_LEVEL_HPP */

source/common/logger/ur_logger.hpp

@@ -4,70 +4,104 @@
 #ifndef UR_LOGGER_HPP
 #define UR_LOGGER_HPP 1
 
-#include "ur_level.hpp"
-#include "ur_sinks.hpp"
+#include <algorithm>
+#include <memory>
+
+#include "ur_logger_details.hpp"
+#include "ur_util.hpp"
 
 namespace logger {
+extern Logger logger;
+
+template <typename... Args>
+inline void debug(const char *format, Args &&...args) {
+    logger.log(logger::Level::DEBUG, format, std::forward<Args>(args)...);
+}
+
+template <typename... Args>
+inline void info(const char *format, Args &&...args) {
+    logger.log(logger::Level::INFO, format, std::forward<Args>(args)...);
+}
+
+template <typename... Args>
+inline void warning(const char *format, Args &&...args) {
+    logger.log(logger::Level::WARN, format, std::forward<Args>(args)...);
+}
+
+template <typename... Args>
+inline void error(const char *format, Args &&...args) {
+    logger.log(logger::Level::ERR, format, std::forward<Args>(args)...);
+}
+
+inline void setLevel(logger::Level level) { logger.setLevel(level); }
+
+inline void setFlushLevel(logger::Level level) { logger.setFlushLevel(level); }
+
+/// @brief Create an instance of the logger with parameters obtained from the respective
+///        environment variable or with default configuration if the env var is empty,
+///        not set, or has the wrong format.
+///        Logger env vars are in the format: UR_LOG_*, ie.:
+///        - UR_LOG_LOADER (logger for loader library),
+///        - UR_LOG_NULL (logger for null adapter).
+///        Example of env var for setting up a loader library logger with logging
+///        level set to `info`, flush level set to `warning`, and output set to
+///        the `out.log` file:
+///             UR_LOG_LOADER="level:info;flush:warning;output:file,out.log"
+/// @param logger_name name that should be appended to the `UR_LOG_` prefix to
+///        get the proper environment variable, ie. "loader"
+/// @return an instance of a logger::Logger. In case of failure in the parsing of
+///         the environment variable, returns a default logger with the following
+///         options:
+///             - log level: quiet, meaning no messages are printed
+///             - flush level: error, meaning that only error messages are guaranteed
+///                            to be printed immediately as they occur
+///             - output: stderr
+inline auto create_logger(std::string logger_name) {
+    std::transform(logger_name.begin(), logger_name.end(), logger_name.begin(),
+                   ::toupper);
+    std::stringstream env_var_name;
+    const auto default_level = logger::Level::QUIET;
+    const auto default_flush_level = logger::Level::ERR;
+    const std::string default_output = "stderr";
+    auto level = default_level;
+    auto flush_level = default_flush_level;
+    std::unique_ptr<logger::Sink> sink;
 
-class Logger {
-  public:
-    Logger(std::unique_ptr<logger::Sink> sink) : sink(std::move(sink)) {
-        if (!this->sink) {
-            throw std::invalid_argument(
-                "Can't create logger with nullptr Sink!");
-        }
-        this->level = logger::Level::QUIET;
+    env_var_name << "UR_LOG_" << logger_name;
+    auto map = getenv_to_map(env_var_name.str().c_str());
+    if (!map.has_value()) {
+        return Logger(std::make_unique<logger::StderrSink>());
     }
 
-    Logger(logger::Level level, std::unique_ptr<logger::Sink> sink)
-        : level(level), sink(std::move(sink)) {
-        if (!this->sink) {
-            throw std::invalid_argument(
-                "Can't create logger with nullptr Sink!");
+    try {
+        auto kv = map->find("level");
+        if (kv != map->end()) {
+            auto value = kv->second.front();
+            level = str_to_level(value);
         }
-    }
-
-    ~Logger() = default;
-
-    void setLevel(logger::Level level) { this->level = level; }
-
-    void setFlushLevel(logger::Level level) {
-        this->sink->setFlushLevel(level);
-    }
-
-    template <typename... Args>
-    void debug(const char *format, Args &&...args) {
-        log(logger::Level::DEBUG, format, std::forward<Args>(args)...);
-    }
 
-    template <typename... Args>
-    void info(const char *format, Args &&...args) {
-        log(logger::Level::INFO, format, std::forward<Args>(args)...);
-    }
-
-    template <typename... Args>
-    void warning(const char *format, Args &&...args) {
-        log(logger::Level::WARN, format, std::forward<Args>(args)...);
-    }
-
-    template <typename... Args>
-    void error(const char *format, Args &&...args) {
-        log(logger::Level::ERR, format, std::forward<Args>(args)...);
-    }
-
-  private:
-    logger::Level level;
-    std::unique_ptr<logger::Sink> sink;
+        kv = map->find("flush");
+        if (kv != map->end()) {
+            auto value = kv->second.front();
+            flush_level = str_to_level(value);
+        }
 
-    template <typename... Args>
-    void log(logger::Level level, const char *format, Args &&...args) {
-        if (level < this->level) {
-            return;
+        std::vector<std::string> values = {default_output};
+        kv = map->find("output");
+        if (kv != map->end()) {
+            values = kv->second;
         }
 
-        sink->log(level, format, std::forward<Args>(args)...);
+        sink = values.size() == 2 ? sink_from_str(values[0], values[1])
+                                  : sink_from_str(values[0]);
+    } catch (const std::invalid_argument &e) {
+        std::cerr << "Error when creating a logger instance from environment variable" << e.what();
+        return Logger(std::make_unique<logger::StderrSink>());
     }
-};
+    sink->setFlushLevel(flush_level);
+
+    return Logger(level, std::move(sink));
+}
 
 } // namespace logger
 

source/common/logger/ur_logger_details.hpp

@@ -0,0 +1,82 @@
+// Copyright (C) 2023 Intel Corporation
+// SPDX-License-Identifier: MIT
+
+#ifndef UR_LOGGER_DETAILS_HPP
+#define UR_LOGGER_DETAILS_HPP 1
+
+#include "ur_level.hpp"
+#include "ur_sinks.hpp"
+
+namespace logger {
+
+class Logger {
+  public:
+    Logger(std::unique_ptr<logger::Sink> sink) : sink(std::move(sink)) {
+        if (!this->sink) {
+            throw std::invalid_argument(
+                "Can't create logger with nullptr Sink!");
+        }
+        this->level = logger::Level::QUIET;
+    }
+
+    Logger(logger::Level level, std::unique_ptr<logger::Sink> sink)
+        : level(level), sink(std::move(sink)) {
+        if (!this->sink) {
+            throw std::invalid_argument(
+                "Can't create logger with nullptr Sink!");
+        }
+    }
+
+    Logger(const Logger &other) : level(other.level), sink(std::move(sink)) {}
+
+    Logger &operator=(Logger other) {
+        std::swap(level, other.level);
+        sink.swap(other.sink);
+        return *this;
+    }
+
+    ~Logger() = default;
+
+    void setLevel(logger::Level level) { this->level = level; }
+
+    void setFlushLevel(logger::Level level) {
+        this->sink->setFlushLevel(level);
+    }
+
+    template <typename... Args>
+    void debug(const char *format, Args &&...args) {
+        log(logger::Level::DEBUG, format, std::forward<Args>(args)...);
+    }
+
+    template <typename... Args>
+    void info(const char *format, Args &&...args) {
+        log(logger::Level::INFO, format, std::forward<Args>(args)...);
+    }
+
+    template <typename... Args>
+    void warning(const char *format, Args &&...args) {
+        log(logger::Level::WARN, format, std::forward<Args>(args)...);
+    }
+
+    template <typename... Args>
+    void error(const char *format, Args &&...args) {
+        log(logger::Level::ERR, format, std::forward<Args>(args)...);
+    }
+
+    template <typename... Args>
+    void log(logger::Level level, const char *format, Args &&...args) {
+        if (level < this->level) {
+            return;
+        }
+
+        sink->log(level, format, std::forward<Args>(args)...);
+    }
+
+  private:
+    logger::Level level;
+    std::unique_ptr<logger::Sink> sink;
+};
+
+} // namespace logger
+
+#endif /* UR_LOGGER_DETAILS_HPP */

source/common/logger/ur_sinks.hpp

@@ -152,6 +152,21 @@ class FileSink : public Sink {
     std::ofstream ofstream;
 };
 
+inline std::unique_ptr<Sink> sink_from_str(std::string name, std::string file_path = "") {
+    if (name == "stdout") {
+        return std::make_unique<logger::StdoutSink>();
+    } else if (name == "stderr") {
+        return std::make_unique<logger::StderrSink>();
+    } else if (name == "file" && !file_path.empty()) {
+        return std::make_unique<logger::FileSink>(file_path.c_str());
+    }
+
+    throw std::invalid_argument(
+        std::string("Parsing error: no valid sink for string '") + name +
+        std::string("' with path '") + file_path + std::string("'.") +
+        std::string("\nValid sink names are: stdout, stderr, file"));
+}
+
 } // namespace logger
 
 #endif /* UR_SINKS_HPP */

source/drivers/null/ur_null.cpp

@@ -8,6 +8,11 @@
  *
  */
 #include "ur_null.hpp"
+#include "logger/ur_logger.hpp"
+
+namespace logger {
+Logger logger = create_logger("null");
+}
 
 namespace driver {
 //////////////////////////////////////////////////////////////////////////

source/loader/ur_lib.cpp

@@ -8,6 +8,7 @@
  *
  */
 #include "ur_lib.hpp"
+#include "logger/ur_logger.hpp"
 #include "ur_loader.hpp"
 #include "ur_proxy_layer.hpp"
 #include "validation/ur_validation_layer.hpp"
@@ -16,6 +17,10 @@
 #include "tracing/ur_tracing_layer.hpp"
 #endif
 
+namespace logger {
+Logger logger = create_logger("loader");
+}
+
 namespace ur_lib {
 ///////////////////////////////////////////////////////////////////////////////
 context_t *context;