util: logging facility
refs #3562
Change-Id: I61d934c5306e1a73b41c81aeb3524d6bf581af3c
diff --git a/src/util/logger.cpp b/src/util/logger.cpp
new file mode 100644
index 0000000..04ad954
--- /dev/null
+++ b/src/util/logger.cpp
@@ -0,0 +1,113 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/**
+ * Copyright (c) 2013-2016 Regents of the University of California.
+ *
+ * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
+ *
+ * ndn-cxx library is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+ * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+ *
+ * You should have received copies of the GNU General Public License and GNU Lesser
+ * General Public License along with ndn-cxx, e.g., in COPYING.md file. If not, see
+ * <http://www.gnu.org/licenses/>.
+ *
+ * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
+ */
+
+#include "logger.hpp"
+
+#include "logging.hpp"
+#include "time.hpp"
+
+#include <cinttypes>
+#include <stdio.h>
+#include <type_traits>
+
+namespace ndn {
+namespace util {
+
+std::ostream&
+operator<<(std::ostream& os, LogLevel level)
+{
+ switch (level) {
+ case LogLevel::FATAL:
+ return os << "FATAL";
+ case LogLevel::NONE:
+ return os << "NONE";
+ case LogLevel::ERROR:
+ return os << "ERROR";
+ case LogLevel::WARN:
+ return os << "WARN";
+ case LogLevel::INFO:
+ return os << "INFO";
+ case LogLevel::DEBUG:
+ return os << "DEBUG";
+ case LogLevel::TRACE:
+ return os << "TRACE";
+ case LogLevel::ALL:
+ return os << "ALL";
+ }
+
+ BOOST_THROW_EXCEPTION(std::invalid_argument("unknown log level " + to_string(static_cast<int>(level))));
+}
+
+LogLevel
+parseLogLevel(const std::string& s)
+{
+ if (s == "FATAL")
+ return LogLevel::FATAL;
+ else if (s == "NONE")
+ return LogLevel::NONE;
+ else if (s == "ERROR")
+ return LogLevel::ERROR;
+ else if (s == "WARN")
+ return LogLevel::WARN;
+ else if (s == "INFO")
+ return LogLevel::INFO;
+ else if (s == "DEBUG")
+ return LogLevel::DEBUG;
+ else if (s == "TRACE")
+ return LogLevel::TRACE;
+ else if (s == "ALL")
+ return LogLevel::ALL;
+
+ BOOST_THROW_EXCEPTION(std::invalid_argument("unrecognized log level '" + s + "'"));
+}
+
+Logger::Logger(const std::string& name)
+ : m_moduleName(name)
+{
+ this->setLevel(LogLevel::NONE);
+ Logging::addLogger(*this);
+}
+
+std::ostream&
+operator<<(std::ostream& os, const LoggerTimestamp&)
+{
+ using namespace ndn::time;
+
+ static const microseconds::rep ONE_SECOND = 1000000;
+ microseconds::rep usecs = duration_cast<microseconds>(
+ system_clock::now().time_since_epoch()).count();
+
+ // 10 (whole seconds) + '.' + 6 (fraction) + '\0'
+ char buffer[10 + 1 + 6 + 1];
+ BOOST_ASSERT_MSG(usecs / ONE_SECOND <= 9999999999L,
+ "whole seconds cannot fit in 10 characters");
+
+ static_assert(std::is_same<microseconds::rep, int_least64_t>::value,
+ "PRIdLEAST64 is incompatible with microseconds::rep");
+ // std::snprintf unavailable in some environments <https://redmine.named-data.net/issues/2299>
+ snprintf(buffer, sizeof(buffer), "%" PRIdLEAST64 ".%06" PRIdLEAST64,
+ usecs / ONE_SECOND, usecs % ONE_SECOND);
+
+ return os << buffer;
+}
+
+} // namespace util
+} // namespace ndn
diff --git a/src/util/logger.hpp b/src/util/logger.hpp
new file mode 100644
index 0000000..58e7b2a
--- /dev/null
+++ b/src/util/logger.hpp
@@ -0,0 +1,167 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/**
+ * Copyright (c) 2013-2016 Regents of the University of California.
+ *
+ * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
+ *
+ * ndn-cxx library is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+ * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+ *
+ * You should have received copies of the GNU General Public License and GNU Lesser
+ * General Public License along with ndn-cxx, e.g., in COPYING.md file. If not, see
+ * <http://www.gnu.org/licenses/>.
+ *
+ * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
+ */
+
+#ifndef NDN_UTIL_LOGGER_HPP
+#define NDN_UTIL_LOGGER_HPP
+
+#include "../common.hpp"
+
+#include <boost/log/common.hpp>
+#include <boost/log/sources/logger.hpp>
+#include <atomic>
+
+namespace ndn {
+namespace util {
+
+/** \brief indicates the severity level of a log message
+ */
+enum class LogLevel {
+ FATAL = -1, ///< fatal (will be logged unconditionally)
+ NONE = 0, ///< no messages
+ ERROR = 1, ///< serious error messages
+ WARN = 2, ///< warning messages
+ INFO = 3, ///< informational messages
+ DEBUG = 4, ///< debug messages
+ TRACE = 5, ///< trace messages (most verbose)
+ ALL = 255 ///< all messages
+};
+
+/** \brief output LogLevel as string
+ * \throw std::invalid_argument unknown \p level
+ */
+std::ostream&
+operator<<(std::ostream& os, LogLevel level);
+
+/** \brief parse LogLevel from string
+ * \throw std::invalid_argument unknown level name
+ */
+LogLevel
+parseLogLevel(const std::string& s);
+
+/** \brief represents a logger in logging facility
+ * \note User should declare a new logger with \p NDN_CXX_LOG_INIT macro.
+ */
+class Logger : public boost::log::sources::logger_mt
+{
+public:
+ explicit
+ Logger(const std::string& name);
+
+ const std::string&
+ getModuleName() const
+ {
+ return m_moduleName;
+ }
+
+ bool
+ isLevelEnabled(LogLevel level) const
+ {
+ return m_currentLevel.load(std::memory_order_relaxed) >= level;
+ }
+
+ void
+ setLevel(LogLevel level)
+ {
+ m_currentLevel.store(level, std::memory_order_relaxed);
+ }
+
+private:
+ const std::string m_moduleName;
+ std::atomic<LogLevel> m_currentLevel;
+};
+
+/** \brief declare a log module
+ */
+#define NDN_CXX_LOG_INIT(name) \
+ namespace { \
+ inline ::ndn::util::Logger& getNdnCxxLogger() \
+ { \
+ static ::ndn::util::Logger logger(BOOST_STRINGIZE(name)); \
+ return logger; \
+ } \
+ } \
+ struct ndn_cxx__allow_trailing_semicolon
+
+/** \brief a tag that writes a timestamp upon stream output
+ * \code
+ * std::clog << LoggerTimestamp();
+ * \endcode
+ */
+struct LoggerTimestamp
+{
+};
+
+/** \brief write a timestamp to \p os
+ * \note This function is thread-safe.
+ */
+std::ostream&
+operator<<(std::ostream& os, const LoggerTimestamp&);
+
+#if (BOOST_VERSION >= 105900) && (BOOST_VERSION < 106000)
+// workaround Boost bug 11549
+#define NDN_CXX_BOOST_LOG(x) BOOST_LOG(x) << ""
+#else
+#define NDN_CXX_BOOST_LOG(x) BOOST_LOG(x)
+#endif
+
+#define NDN_CXX_LOG(lvl, lvlstr, expression) \
+ do { \
+ if (getNdnCxxLogger().isLevelEnabled(::ndn::util::LogLevel::lvl)) { \
+ NDN_CXX_BOOST_LOG(getNdnCxxLogger()) << ::ndn::util::LoggerTimestamp{} \
+ << " " BOOST_STRINGIZE(lvlstr) ": [" << getNdnCxxLogger().getModuleName() << "] " \
+ << expression; \
+ } \
+ } while (false)
+
+/** \brief log at TRACE level
+ * \pre A log module must be declared in the same translation unit.
+ */
+#define NDN_CXX_LOG_TRACE(expression) NDN_CXX_LOG(TRACE, TRACE, expression)
+
+/** \brief log at DEBUG level
+ * \pre A log module must be declared in the same translation unit.
+ */
+#define NDN_CXX_LOG_DEBUG(expression) NDN_CXX_LOG(DEBUG, DEBUG, expression)
+
+/** \brief log at INFO level
+ * \pre A log module must be declared in the same translation unit.
+ */
+#define NDN_CXX_LOG_INFO(expression) NDN_CXX_LOG(INFO, INFO, expression)
+
+/** \brief log at WARN level
+ * \pre A log module must be declared in the same translation unit.
+ */
+#define NDN_CXX_LOG_WARN(expression) NDN_CXX_LOG(WARN, WARNING, expression)
+
+/** \brief log at ERROR level
+ * \pre A log module must be declared in the same translation unit.
+ */
+#define NDN_CXX_LOG_ERROR(expression) NDN_CXX_LOG(ERROR, ERROR, expression)
+
+/** \brief log at FATAL level
+ * \pre A log module must be declared in the same translation unit.
+ */
+#define NDN_CXX_LOG_FATAL(expression) NDN_CXX_LOG(FATAL, FATAL, expression)
+
+} // namespace util
+} // namespace ndn
+
+#endif // NDN_UTIL_LOGGER_HPP
diff --git a/src/util/logging.cpp b/src/util/logging.cpp
new file mode 100644
index 0000000..dd10c4d
--- /dev/null
+++ b/src/util/logging.cpp
@@ -0,0 +1,209 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/**
+ * Copyright (c) 2013-2016 Regents of the University of California.
+ *
+ * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
+ *
+ * ndn-cxx library is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+ * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+ *
+ * You should have received copies of the GNU General Public License and GNU Lesser
+ * General Public License along with ndn-cxx, e.g., in COPYING.md file. If not, see
+ * <http://www.gnu.org/licenses/>.
+ *
+ * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
+ */
+
+#include "logging.hpp"
+#include "logger.hpp"
+
+#include <boost/log/expressions.hpp>
+#include <cstdlib>
+#include <fstream>
+
+namespace ndn {
+namespace util {
+
+static const LogLevel INITIAL_DEFAULT_LEVEL = LogLevel::NONE;
+
+Logging&
+Logging::get()
+{
+ // Initialization of block-scope variables with static storage duration is thread-safe.
+ // See ISO C++ standard [stmt.dcl]/4
+ static Logging instance;
+ return instance;
+}
+
+Logging::Logging()
+{
+ this->setDestinationImpl(shared_ptr<std::ostream>(&std::clog, bind([]{})));
+
+ const char* environ = std::getenv("NDN_CXX_LOG");
+ if (environ != nullptr) {
+ this->setLevelImpl(environ);
+ }
+}
+
+void
+Logging::addLoggerImpl(Logger& logger)
+{
+ std::lock_guard<std::mutex> lock(m_mutex);
+
+ const std::string& moduleName = logger.getModuleName();
+ m_loggers.insert({moduleName, &logger});
+
+ auto levelIt = m_enabledLevel.find(moduleName);
+ if (levelIt == m_enabledLevel.end()) {
+ levelIt = m_enabledLevel.find("*");
+ }
+ LogLevel level = levelIt == m_enabledLevel.end() ? INITIAL_DEFAULT_LEVEL : levelIt->second;
+ logger.setLevel(level);
+}
+
+#ifdef NDN_CXX_HAVE_TESTS
+bool
+Logging::removeLogger(Logger& logger)
+{
+ const std::string& moduleName = logger.getModuleName();
+ auto range = m_loggers.equal_range(moduleName);
+ for (auto i = range.first; i != range.second; ++i) {
+ if (i->second == &logger) {
+ m_loggers.erase(i);
+ return true;
+ }
+ }
+ return false;
+}
+#endif // NDN_CXX_HAVE_TESTS
+
+void
+Logging::setLevelImpl(const std::string& moduleName, LogLevel level)
+{
+ std::lock_guard<std::mutex> lock(m_mutex);
+
+ if (moduleName == "*") {
+ this->setDefaultLevel(level);
+ return;
+ }
+
+ m_enabledLevel[moduleName] = level;
+ auto range = m_loggers.equal_range(moduleName);
+ for (auto i = range.first; i != range.second; ++i) {
+ i->second->setLevel(level);
+ }
+}
+
+void
+Logging::setDefaultLevel(LogLevel level)
+{
+ m_enabledLevel.clear();
+ m_enabledLevel["*"] = level;
+
+ for (auto i = m_loggers.begin(); i != m_loggers.end(); ++i) {
+ i->second->setLevel(level);
+ }
+}
+
+void
+Logging::setLevelImpl(const std::string& config)
+{
+ std::stringstream ss(config);
+ std::string configModule;
+ while (std::getline(ss, configModule, ':')) {
+ size_t ind = configModule.find('=');
+ if (ind == std::string::npos) {
+ BOOST_THROW_EXCEPTION(std::invalid_argument("malformed logging config: '=' is missing"));
+ }
+
+ std::string moduleName = configModule.substr(0, ind);
+ LogLevel level = parseLogLevel(configModule.substr(ind+1));
+
+ this->setLevelImpl(moduleName, level);
+ }
+}
+
+#ifdef NDN_CXX_HAVE_TESTS
+std::string
+Logging::getLevels() const
+{
+ std::ostringstream os;
+
+ auto defaultLevelIt = m_enabledLevel.find("*");
+ if (defaultLevelIt != m_enabledLevel.end()) {
+ os << "*=" << defaultLevelIt->second << ':';
+ }
+
+ for (auto it = m_enabledLevel.begin(); it != m_enabledLevel.end(); ++it) {
+ if (it->first == "*") {
+ continue;
+ }
+ os << it->first << '=' << it->second << ':';
+ }
+
+ std::string s = os.str();
+ if (!s.empty()) {
+ s.pop_back(); // delete last ':'
+ }
+ return s;
+}
+#endif // NDN_CXX_HAVE_TESTS
+
+#ifdef NDN_CXX_HAVE_TESTS
+void
+Logging::resetLevels()
+{
+ this->setDefaultLevel(INITIAL_DEFAULT_LEVEL);
+ m_enabledLevel.clear();
+}
+#endif // NDN_CXX_HAVE_TESTS
+
+void
+Logging::setDestination(std::ostream& os)
+{
+ setDestination(shared_ptr<std::ostream>(&os, bind([]{})));
+}
+
+void
+Logging::setDestinationImpl(shared_ptr<std::ostream> os)
+{
+ std::lock_guard<std::mutex> lock(m_mutex);
+
+ m_destination = os;
+
+ auto backend = boost::make_shared<boost::log::sinks::text_ostream_backend>();
+ backend->auto_flush(true);
+ backend->add_stream(boost::shared_ptr<std::ostream>(os.get(), bind([]{})));
+
+ if (m_sink != nullptr) {
+ boost::log::core::get()->remove_sink(m_sink);
+ m_sink->flush();
+ m_sink.reset();
+ }
+
+ m_sink = boost::make_shared<Sink>(backend);
+ m_sink->set_formatter(boost::log::expressions::stream << boost::log::expressions::message);
+ boost::log::core::get()->add_sink(m_sink);
+}
+
+#ifdef NDN_CXX_HAVE_TESTS
+shared_ptr<std::ostream>
+Logging::getDestination()
+{
+ return m_destination;
+}
+#endif // NDN_CXX_HAVE_TESTS
+
+void
+Logging::flushImpl()
+{
+ m_sink->flush();
+}
+
+} // namespace util
+} // namespace ndn
diff --git a/src/util/logging.hpp b/src/util/logging.hpp
new file mode 100644
index 0000000..af000c4
--- /dev/null
+++ b/src/util/logging.hpp
@@ -0,0 +1,187 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/**
+ * Copyright (c) 2013-2016 Regents of the University of California.
+ *
+ * This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
+ *
+ * ndn-cxx library is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Lesser General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * ndn-cxx library is distributed in the hope that it will be useful, but WITHOUT ANY
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+ * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
+ *
+ * You should have received copies of the GNU General Public License and GNU Lesser
+ * General Public License along with ndn-cxx, e.g., in COPYING.md file. If not, see
+ * <http://www.gnu.org/licenses/>.
+ *
+ * See AUTHORS.md for complete list of ndn-cxx authors and contributors.
+ */
+
+#ifndef NDN_UTIL_LOGGING_HPP
+#define NDN_UTIL_LOGGING_HPP
+
+#include "../common.hpp"
+
+#include <boost/log/sinks.hpp>
+#include <mutex>
+#include <unordered_map>
+
+namespace ndn {
+namespace util {
+
+enum class LogLevel;
+class Logger;
+
+/** \brief controls the logging facility
+ *
+ * \note Public static methods are thread safe.
+ * Non-public methods are not guaranteed to be thread safe.
+ */
+class Logging : noncopyable
+{
+public:
+ /** \brief register a new logger
+ * \note App should declare a new logger with \p NDN_CXX_LOG_INIT macro.
+ */
+ static void
+ addLogger(Logger& logger);
+
+ /** \brief set severity level
+ * \param moduleName logger name, or "*" for default level
+ * \param level minimum severity level
+ *
+ * Log messages are output only if its severity is greater than the set minimum severity level.
+ * Initial default severity level is \p LogLevel::NONE which enables FATAL only.
+ *
+ * Changing the default level overwrites individual settings.
+ */
+ static void
+ setLevel(const std::string& moduleName, LogLevel level);
+
+ /** \brief set severity levels with a config string
+ * \param config colon-separate key=value pairs
+ * \throw std::invalid_argument config string is malformed
+ *
+ * \code
+ * Logging::setSeverityLevels("*=INFO:Face=DEBUG:NfdController=WARN");
+ * \endcode
+ * is equivalent to
+ * \code
+ * Logging::setSeverityLevel("*", LogLevel::INFO);
+ * Logging::setSeverityLevel("Face", LogLevel::DEBUG);
+ * Logging::setSeverityLevel("NfdController", LogLevel::WARN);
+ * \endcode
+ */
+ static void
+ setLevel(const std::string& config);
+
+ /** \brief set log destination
+ * \param os a stream for log output
+ *
+ * Initial destination is \p std::clog .
+ */
+ static void
+ setDestination(shared_ptr<std::ostream> os);
+
+ /** \brief set log destination
+ * \param os a stream for log output; caller must ensure this is valid
+ * until setDestination is invoked again or program exits
+ *
+ * This is equivalent to setDestination(shared_ptr<std::ostream>(&os, nullDeleter))
+ */
+ static void
+ setDestination(std::ostream& os);
+
+ /** \brief flush log backend
+ *
+ * This ensures log messages are written to the destination stream.
+ */
+ static void
+ flush();
+
+private:
+ Logging();
+
+ void
+ addLoggerImpl(Logger& logger);
+
+ void
+ setLevelImpl(const std::string& moduleName, LogLevel level);
+
+ void
+ setDefaultLevel(LogLevel level);
+
+ void
+ setLevelImpl(const std::string& config);
+
+ void
+ setDestinationImpl(shared_ptr<std::ostream> os);
+
+ void
+ flushImpl();
+
+NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PRIVATE:
+ static Logging&
+ get();
+
+#ifdef NDN_CXX_HAVE_TESTS
+ bool
+ removeLogger(Logger& logger);
+
+ std::string
+ getLevels() const;
+
+ void
+ resetLevels();
+
+ shared_ptr<std::ostream>
+ getDestination();
+#endif // NDN_CXX_HAVE_TESTS
+
+private:
+ std::mutex m_mutex;
+ std::unordered_map<std::string, LogLevel> m_enabledLevel; ///< moduleName => minimum level
+ std::unordered_multimap<std::string, Logger*> m_loggers; ///< moduleName => logger
+
+ shared_ptr<std::ostream> m_destination;
+ typedef boost::log::sinks::asynchronous_sink<boost::log::sinks::text_ostream_backend> Sink;
+ boost::shared_ptr<Sink> m_sink;
+};
+
+inline void
+Logging::addLogger(Logger& logger)
+{
+ get().addLoggerImpl(logger);
+}
+
+inline void
+Logging::setLevel(const std::string& moduleName, LogLevel level)
+{
+ get().setLevelImpl(moduleName, level);
+}
+
+inline void
+Logging::setLevel(const std::string& config)
+{
+ get().setLevelImpl(config);
+}
+
+inline void
+Logging::setDestination(shared_ptr<std::ostream> os)
+{
+ get().setDestinationImpl(os);
+}
+
+inline void
+Logging::flush()
+{
+ get().flushImpl();
+}
+
+
+} // namespace util
+} // namespace ndn
+
+#endif // NDN_UTIL_LOGGING_HPP