arrow/util/logger.h

0001 // Licensed to the Apache Software Foundation (ASF) under one
0002 // or more contributor license agreements.  See the NOTICE file
0003 // distributed with this work for additional information
0004 // regarding copyright ownership.  The ASF licenses this file
0005 // to you under the Apache License, Version 2.0 (the
0006 // "License"); you may not use this file except in compliance
0007 // with the License.  You may obtain a copy of the License at
0008 //
0009 //   http://www.apache.org/licenses/LICENSE-2.0
0010 //
0011 // Unless required by applicable law or agreed to in writing,
0012 // software distributed under the License is distributed on an
0013 // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
0014 // KIND, either express or implied.  See the License for the
0015 // specific language governing permissions and limitations
0016 // under the License.
0017
0018 #pragma once
0019
0020 #include <chrono>
0021 #include <iosfwd>
0022 #include <memory>
0023 #include <string_view>
0024
0025 #include "arrow/result.h"
0026 #include "arrow/status.h"
0027 #include "arrow/util/logging.h"
0028 #include "arrow/util/macros.h"
0029 #include "arrow/util/visibility.h"
0030
0031 namespace arrow {
0032 namespace util {
0033
0034 struct SourceLocation {
0035   const char* file = "";
0036   int line = 0;
0037 };
0038
0039 struct LogDetails {
0040   ArrowLogLevel severity = ArrowLogLevel::ARROW_INFO;
0041   std::chrono::system_clock::time_point timestamp = std::chrono::system_clock::now();
0042   SourceLocation source_location{};
0043   std::string_view message = "";
0044 };
0045
0046 /// \brief A base interface for custom loggers.
0047 ///
0048 /// Loggers can be added to the LoggerRegistry for global access or directly provided to
0049 /// certain logging utilities.
0050 class Logger {
0051  public:
0052   virtual ~Logger() = default;
0053
0054   virtual void Log(const LogDetails& details) = 0;
0055
0056   virtual bool Flush(std::chrono::microseconds timeout) { return true; }
0057   bool Flush() { return this->Flush(std::chrono::microseconds::max()); }
0058
0059   virtual bool is_enabled() const { return true; }
0060
0061   virtual ArrowLogLevel severity_threshold() const { return ArrowLogLevel::ARROW_TRACE; }
0062 };
0063
0064 /// \brief Creates a simple logger that redirects output to std::cerr
0065 ARROW_EXPORT std::shared_ptr<Logger> MakeOStreamLogger(ArrowLogLevel severity_threshold);
0066 /// \brief Creates a simple logger that redirects output to the provided ostream
0067 ARROW_EXPORT std::shared_ptr<Logger> MakeOStreamLogger(ArrowLogLevel severity_threshold,
0068                                                        std::ostream& sink);
0069
0070 class ARROW_EXPORT LoggerRegistry {
0071  public:
0072   /// \brief Add a logger to the registry with the associated name
0073   ///
0074   /// Returns Invalid if a logger with the provided name already exists. Users should call
0075   /// `UnregisterLogger` first if they wish to overwrite it.
0076   static Status RegisterLogger(std::string_view name, std::shared_ptr<Logger> logger);
0077
0078   /// \brief Remove a logger from the registry
0079   static void UnregisterLogger(std::string_view name);
0080
0081   /// \brief Return the logger associated with the provided name
0082   ///
0083   /// If `name` is empty, the default logger is returned. If `name` doesn't match any of
0084   /// the registered loggers then a non-null noop logger is returned
0085   static std::shared_ptr<Logger> GetLogger(std::string_view name = "");
0086
0087   /// \brief Return the default logger
0088   static std::shared_ptr<Logger> GetDefaultLogger();
0089   /// \brief Set the default logger
0090   static void SetDefaultLogger(std::shared_ptr<Logger> logger);
0091 };
0092
0093 /// \brief Represents a single log record to be emitted by an underlying logger
0094 class ARROW_EXPORT LogMessage {
0095  public:
0096   /// \brief Construct a LogMessage with the provided underlying logger
0097   LogMessage(ArrowLogLevel severity, std::shared_ptr<Logger> logger,
0098              SourceLocation source_location = {});
0099   /// \brief Construct a LogMessage with the provided logger name, which will be used to
0100   /// find an underlying logger in the registry
0101   LogMessage(ArrowLogLevel severity, std::string_view logger_name,
0102              SourceLocation source_location = {});
0103
0104   std::ostream& Stream();
0105
0106   // Convenience method - mainly for use in ARROW_LOG_* macros. This prevents unnecessary
0107   // argument evaluation when log statements are stripped in certain builds
0108   template <typename... Args>
0109   LogMessage& Append(Args&&... args) {
0110     if constexpr (sizeof...(Args) > 0) {
0111       if (CheckIsEnabled()) {
0112         (Stream() << ... << args);
0113       }
0114     }
0115     return *this;
0116   }
0117
0118  private:
0119   bool CheckIsEnabled();
0120
0121   class Impl;
0122   std::shared_ptr<Impl> impl_;
0123 };
0124
0125 }  // namespace util
0126 }  // namespace arrow
0127
0128 // For the following macros, log statements with a lower severity than
0129 // `ARROW_MINIMUM_LOG_LEVEL` will be stripped from the build
0130 #ifndef ARROW_MINIMUM_LOG_LEVEL
0131 #  define ARROW_MINIMUM_LOG_LEVEL -1000
0132 #endif
0133
0134 #define ARROW_LOGGER_INTERNAL(LOGGER, LEVEL)                                      \
0135   (::arrow::util::LogMessage(::arrow::util::ArrowLogLevel::ARROW_##LEVEL, LOGGER, \
0136                              ::arrow::util::SourceLocation{__FILE__, __LINE__}))
0137
0138 static_assert(static_cast<int>(::arrow::util::ArrowLogLevel::ARROW_TRACE) == -2);
0139 #if ARROW_MINIMUM_LOG_LEVEL <= -2
0140 #  define ARROW_LOGGER_TRACE(LOGGER, ...) \
0141     (ARROW_LOGGER_INTERNAL(LOGGER, TRACE).Append(__VA_ARGS__))
0142 #else
0143 #  define ARROW_LOGGER_TRACE(...) ARROW_UNUSED(0)
0144 #endif
0145
0146 static_assert(static_cast<int>(::arrow::util::ArrowLogLevel::ARROW_DEBUG) == -1);
0147 #if ARROW_MINIMUM_LOG_LEVEL <= -1
0148 #  define ARROW_LOGGER_DEBUG(LOGGER, ...) \
0149     (ARROW_LOGGER_INTERNAL(LOGGER, DEBUG).Append(__VA_ARGS__))
0150 #else
0151 #  define ARROW_LOGGER_DEBUG(...) ARROW_UNUSED(0)
0152 #endif
0153
0154 static_assert(static_cast<int>(::arrow::util::ArrowLogLevel::ARROW_INFO) == 0);
0155 #if ARROW_MINIMUM_LOG_LEVEL <= 0
0156 #  define ARROW_LOGGER_INFO(LOGGER, ...) \
0157     (ARROW_LOGGER_INTERNAL(LOGGER, INFO).Append(__VA_ARGS__))
0158 #else
0159 #  define ARROW_LOGGER_INFO(...) ARROW_UNUSED(0)
0160 #endif
0161
0162 static_assert(static_cast<int>(::arrow::util::ArrowLogLevel::ARROW_WARNING) == 1);
0163 #if ARROW_MINIMUM_LOG_LEVEL <= 1
0164 #  define ARROW_LOGGER_WARNING(LOGGER, ...) \
0165     (ARROW_LOGGER_INTERNAL(LOGGER, WARNING).Append(__VA_ARGS__))
0166 #else
0167 #  define ARROW_LOGGER_WARNING(...) ARROW_UNUSED(0)
0168 #endif
0169
0170 static_assert(static_cast<int>(::arrow::util::ArrowLogLevel::ARROW_ERROR) == 2);
0171 #if ARROW_MINIMUM_LOG_LEVEL <= 2
0172 #  define ARROW_LOGGER_ERROR(LOGGER, ...) \
0173     (ARROW_LOGGER_INTERNAL(LOGGER, ERROR).Append(__VA_ARGS__))
0174 #else
0175 #  define ARROW_LOGGER_ERROR(...) ARROW_UNUSED(0)
0176 #endif
0177
0178 static_assert(static_cast<int>(::arrow::util::ArrowLogLevel::ARROW_FATAL) == 3);
0179 #if ARROW_MINIMUM_LOG_LEVEL <= 3
0180 #  define ARROW_LOGGER_FATAL(LOGGER, ...) \
0181     (ARROW_LOGGER_INTERNAL(LOGGER, FATAL).Append(__VA_ARGS__))
0182 #else
0183 #  define ARROW_LOGGER_FATAL(...) ARROW_UNUSED(0)
0184 #endif
0185
0186 #define ARROW_LOGGER_CALL(LOGGER, LEVEL, ...) ARROW_LOGGER_##LEVEL(LOGGER, __VA_ARGS__)