folly::LogCategory Class Reference

#include <LogCategory.h>

Public Member Functions
	LogCategory (LoggerDB *db)
	LogCategory (folly::StringPiece name, LogCategory *parent)
const std::string &	getName () const
LogLevel	getLevel () const
std::pair< LogLevel, bool >	getLevelInfo () const
LogLevel	getEffectiveLevel () const
LogLevel	getEffectiveLevelRelaxed () const
bool	logCheck (LogLevel level) const
void	setLevel (LogLevel level, bool inherit=true)
LoggerDB *	getDB () const
void	addHandler (std::shared_ptr< LogHandler > handler)
void	clearHandlers ()
std::vector< std::shared_ptr< LogHandler > >	getHandlers () const
void	replaceHandlers (std::vector< std::shared_ptr< LogHandler >> handlers)
void	updateHandlers (const std::unordered_map< std::shared_ptr< LogHandler >, std::shared_ptr< LogHandler >> &handlerMap)
void	admitMessage (const LogMessage &message) const
void	setLevelLocked (LogLevel level, bool inherit)
void	registerXlogLevel (std::atomic< LogLevel > *levelPtr)

Private Types
enum	: uint32_t { FLAG_INHERIT = 0x80000000 }

Private Member Functions
	LogCategory (LogCategory const &)=delete
LogCategory &	operator= (LogCategory const &)=delete
	LogCategory (LogCategory &&)=delete
LogCategory &	operator= (LogCategory &&)=delete
void	processMessage (const LogMessage &message) const
void	updateEffectiveLevel (LogLevel newEffectiveLevel)
void	parentLevelUpdated (LogLevel parentEffectiveLevel)

Private Attributes
std::atomic< LogLevel >	effectiveLevel_ {LogLevel::MAX_LEVEL}
std::atomic< uint32_t >	level_ {0}
LogCategory *const	parent_ {nullptr}
const std::string	name_
folly::Synchronized< std::vector< std::shared_ptr< LogHandler > > >	handlers_
LoggerDB *const	db_ {nullptr}
LogCategory *	firstChild_ {nullptr}
LogCategory *	nextSibling_ {nullptr}
std::vector< std::atomic< LogLevel > * >	xlogLevels_

Detailed Description

LogCategory stores all of the logging configuration for a specific log category.

This class is separate from Logger to allow multiple Logger objects to all refer to the same log category. Logger can be thought of as a small wrapper class that behaves like a pointer to a LogCategory object.

Definition at line 41 of file LogCategory.h.

Member Enumeration Documentation

anonymous enum : uint32_t

private

Enumerator
FLAG_INHERIT

Definition at line 222 of file LogCategory.h.

: uint32_t { FLAG_INHERIT = 0x80000000 };

Constructor & Destructor Documentation

folly::LogCategory::LogCategory ( LoggerDB *  db )

explicit

Create the root LogCategory.

This should generally only be invoked by LoggerDB.

Definition at line 32 of file LogCategory.cpp.

References db_, folly::ERR, level_, name_, parent_, and uint32_t.

    : effectiveLevel_{LogLevel::ERR},
      level_{static_cast<uint32_t>(LogLevel::ERR)},
      parent_{nullptr},
      name_{},
      db_{db} {}

folly::LogCategory::LogCategory	(	folly::StringPiece	name,
		LogCategory *	parent
	)

Create a new LogCategory.

This should only be invoked by LoggerDB, while holding the main LoggerDB lock.

The name argument should already be in canonical form.

This constructor automatically adds this new LogCategory to the parent category's firstChild_ linked-list.

Definition at line 39 of file LogCategory.cpp.

References folly::LogName::canonicalize(), db_, firstChild_, FLAG_INHERIT, getEffectiveLevel(), level_, folly::MAX_LEVEL, name, name_, nextSibling_, parent, parent_, and uint32_t.

    : effectiveLevel_{parent->getEffectiveLevel()},
      level_{static_cast<uint32_t>(LogLevel::MAX_LEVEL) | FLAG_INHERIT},
      parent_{parent},
      name_{LogName::canonicalize(name)},
      db_{parent->getDB()},
      nextSibling_{parent_->firstChild_} {
  parent_->firstChild_ = this;
}

folly::LogCategory::LogCategory ( LogCategory const &  )

privatedelete

folly::LogCategory::LogCategory ( LogCategory &&  )

privatedelete

Member Function Documentation

void folly::LogCategory::addHandler

(

std::shared_ptr< LogHandler >

handler

)

Attach a LogHandler to this category.

Definition at line 127 of file LogCategory.cpp.

References handlers_, and folly::gen::move.

Referenced by getDB(), and TEST_F().

                                                              {
  auto handlers = handlers_.wlock();
  handlers->emplace_back(std::move(handler));
}

void folly::LogCategory::admitMessage

(

const LogMessage &

message

)

const

Admit a message into the LogCategory hierarchy to be logged.

The caller is responsible for having already performed log level admittance checks.

This method generally should be invoked only through the logging macros, rather than calling this directly.

Definition at line 49 of file LogCategory.cpp.

References db_, folly::LoggerDB::flushAllHandlers(), folly::LogMessage::getFileName(), folly::LogMessage::getLevel(), folly::LogMessage::getLineNumber(), folly::LogMessage::getMessage(), folly::isLogLevelFatal(), processMessage(), and folly::writeFull().

Referenced by getDB(), and folly::LogStreamProcessor::logNow().

                                                              {
  processMessage(message);

  // If this is a fatal message, flush the handlers to make sure the log
  // message was written out, then crash.
  if (isLogLevelFatal(message.getLevel())) {
    auto numHandlers = db_->flushAllHandlers();
    if (numHandlers == 0) {
      // No log handlers were configured.
      // Print the message to stderr, to make sure we always print the reason
      // we are crashing somewhere.
      auto msg = folly::to<std::string>(
          "FATAL:",
          message.getFileName(),
          ":",
          message.getLineNumber(),
          ": ",
          message.getMessage(),
          "\n");
      folly::writeFull(STDERR_FILENO, msg.data(), msg.size());
    }
    std::abort();
  }
}

void folly::LogCategory::clearHandlers

(

)

Remove all LogHandlers from this category.

Definition at line 132 of file LogCategory.cpp.

References handlers_.

Referenced by getDB().

                                {
  std::vector<std::shared_ptr<LogHandler>> emptyHandlersList;
  // Swap out the handlers list with the handlers_ lock held.
  {
    auto handlers = handlers_.wlock();
    handlers->swap(emptyHandlersList);
  }
  // Destroy emptyHandlersList now that the handlers_ lock is released.
  // This way we don't hold the handlers_ lock while invoking any of the
  // LogHandler destructors.
}

LoggerDB* folly::LogCategory::getDB ( ) const

inline

Get the LoggerDB that this LogCategory belongs to.

This is almost always the main LoggerDB singleton returned by LoggerDB::get(). The logging unit tests are the main location that creates alternative LoggerDB objects.

Definition at line 148 of file LogCategory.h.

References addHandler(), admitMessage(), clearHandlers(), db_, getHandlers(), handler(), registerXlogLevel(), replaceHandlers(), setLevelLocked(), and updateHandlers().

                          {
    return db_;
  }

LogLevel folly::LogCategory::getEffectiveLevel ( ) const

inline

Get the effective level for this log category.

This is the minimum log level of this category and all of its parents. Log messages below this level will be ignored, while messages at or above this level need to be processed by this category or one of its parents.

Definition at line 95 of file LogCategory.h.

References effectiveLevel_.

Referenced by LogCategory(), setLevelLocked(), and folly::LoggerDB::xlogInit().

                                     {
    return effectiveLevel_.load(std::memory_order_acquire);
  }

LogLevel folly::LogCategory::getEffectiveLevelRelaxed ( ) const

inline

Get the effective log level using std::memory_order_relaxed.

This is primarily used for log message checks. Most other callers should use getEffectiveLevel() above to be more conservative with regards to memory ordering.

Definition at line 106 of file LogCategory.h.

References effectiveLevel_.

                                            {
    return effectiveLevel_.load(std::memory_order_relaxed);
  }

std::vector< std::shared_ptr< LogHandler > > folly::LogCategory::getHandlers

(

)

const

Get the list of LogHandlers attached to this category.

Definition at line 144 of file LogCategory.cpp.

References handlers_.

Referenced by getDB().

                                                                    {
  return *(handlers_.rlock());
}

LogLevel folly::LogCategory::getLevel ( ) const

inline

Get the level for this log category.

Definition at line 73 of file LogCategory.h.

References FLAG_INHERIT, and level_.

                            {
    return static_cast<LogLevel>(
        level_.load(std::memory_order_acquire) & ~FLAG_INHERIT);
  }

std::pair<LogLevel, bool> folly::LogCategory::getLevelInfo ( ) const

inline

Get the log level and inheritance flag.

Definition at line 81 of file LogCategory.h.

References FLAG_INHERIT, level_, and folly::value().

                                               {
    auto value = level_.load(std::memory_order_acquire);
    return {static_cast<LogLevel>(value & ~FLAG_INHERIT),
            bool(value & FLAG_INHERIT)};
  }

const std::string& folly::LogCategory::getName ( ) const

inline

Get the name of this log category.

Definition at line 66 of file LogCategory.h.

References name_.

                                   {
    return name_;
  }

bool folly::LogCategory::logCheck ( LogLevel  level ) const

inline

Check whether this Logger or any of its parent Loggers would do anything with a log message at the given level.

Definition at line 114 of file LogCategory.h.

References effectiveLevel_, and setLevel().

                                      {
    // We load the effective level using std::memory_order_relaxed.
    //
    // We want to make log checks as lightweight as possible.  It's fine if we
    // don't immediately respond to changes made to the log level from other
    // threads.  We can wait until some other operation triggers a memory
    // barrier before we honor the new log level setting.  No other memory
    // accesses depend on the log level value.  Callers should not rely on all
    // other threads to immediately stop logging as soon as they decrease the
    // log level for a given category.
    return effectiveLevel_.load(std::memory_order_relaxed) <= level;
  }

LogCategory& folly::LogCategory::operator= ( LogCategory const &  )

privatedelete

LogCategory& folly::LogCategory::operator= ( LogCategory &&  )

privatedelete

void folly::LogCategory::parentLevelUpdated ( LogLevel  parentEffectiveLevel )

private

Definition at line 227 of file LogCategory.cpp.

References FLAG_INHERIT, level_, min, uint32_t, and updateEffectiveLevel().

Referenced by updateEffectiveLevel().

                                                                  {
  uint32_t levelValue = level_.load(std::memory_order_acquire);
  auto inherit = (levelValue & FLAG_INHERIT);
  if (!inherit) {
    return;
  }

  auto myLevel = static_cast<LogLevel>(levelValue & ~FLAG_INHERIT);
  auto newEffectiveLevel = std::min(myLevel, parentEffectiveLevel);
  updateEffectiveLevel(newEffectiveLevel);
}

void folly::LogCategory::processMessage ( const LogMessage &  message ) const

private

Definition at line 74 of file LogCategory.cpp.

References folly::exceptionStr(), handlers_, folly::LoggerDB::internalWarning(), name_, parent_, processMessage(), and uint32_t.

Referenced by admitMessage(), and processMessage().

                                                                {
  // Make a copy of any attached LogHandlers, so we can release the handlers_
  // lock before holding them.
  //
  // In the common case there will only be a small number of handlers.  Use a
  // std::array in this case to avoid a heap allocation for the vector.
  const std::shared_ptr<LogHandler>* handlers = nullptr;
  size_t numHandlers = 0;
  constexpr uint32_t kSmallOptimizationSize = 5;
  std::array<std::shared_ptr<LogHandler>, kSmallOptimizationSize> handlersArray;
  std::vector<std::shared_ptr<LogHandler>> handlersVector;
  {
    auto lockedHandlers = handlers_.rlock();
    numHandlers = lockedHandlers->size();
    if (numHandlers <= kSmallOptimizationSize) {
      for (size_t n = 0; n < numHandlers; ++n) {
        handlersArray[n] = (*lockedHandlers)[n];
      }
      handlers = handlersArray.data();
    } else {
      handlersVector = *lockedHandlers;
      handlers = handlersVector.data();
    }
  }

  for (size_t n = 0; n < numHandlers; ++n) {
    try {
      handlers[n]->handleMessage(message, this);
    } catch (const std::exception& ex) {
      // Use LoggerDB::internalWarning() to report the error, but continue
      // trying to log the message to any other handlers attached to ourself or
      // one of our parent categories.
      LoggerDB::internalWarning(
          __FILE__,
          __LINE__,
          "log handler for category \"",
          name_,
          "\" threw an error: ",
          folly::exceptionStr(ex));
    }
  }

  // Propagate the message up to our parent LogCategory.
  //
  // Maybe in the future it might be worth adding a flag to control if a
  // LogCategory should propagate messages to its parent or not.  (This would
  // be similar to log4j's "additivity" flag.)
  // For now I don't have a strong use case for this.
  if (parent_) {
    parent_->processMessage(message);
  }
}

void folly::LogCategory::registerXlogLevel

(

std::atomic< LogLevel > *

levelPtr

)

Register a std::atomic<LogLevel> value used by XLOG*() macros to check the effective level for this category.

The LogCategory will keep this value updated whenever its effective log level changes.

This function should only be invoked by LoggerDB, and the LoggerDB lock must be held when calling it.

Definition at line 239 of file LogCategory.cpp.

References xlogLevels_.

Referenced by getDB().

                                                                 {
  xlogLevels_.push_back(levelPtr);
}

void folly::LogCategory::replaceHandlers

(

std::vector< std::shared_ptr< LogHandler >>

handlers

)

Replace the list of LogHandlers with a completely new list.

Definition at line 148 of file LogCategory.cpp.

References handlers_.

Referenced by getDB(), and folly::LoggerDB::updateConfig().

                                                   {
  return handlers_.wlock()->swap(handlers);
}

void folly::LogCategory::setLevel	(	LogLevel	level,
		bool	inherit = true
	)

Set the log level for this LogCategory.

Messages logged to a specific log category will be ignored unless the message log level is greater than the LogCategory's effective log level.

If inherit is true, LogCategory's effective log level is the minimum of its level and its parent category's effective log level. If inherit is false, the LogCategory's effective log level is simply its log level. (Setting inherit to false is necessary if you want a child LogCategory to use a less verbose level than its parent categories.)

Definition at line 165 of file LogCategory.cpp.

References db_, and folly::LoggerDB::setLevel().

Referenced by logCheck().

                                                       {
  // We have to set the level through LoggerDB, since we require holding
  // the LoggerDB lock to iterate through our children in case our effective
  // level changes.
  db_->setLevel(this, level, inherit);
}

void folly::LogCategory::setLevelLocked	(	LogLevel	level,
		bool	inherit
	)

Note: setLevelLocked() may only be called while holding the LoggerDB loggersByName_ lock. It is safe to call this while holding the loggersByName_ lock in read-mode; holding it exclusively is not required.

This method should only be invoked by LoggerDB.

Definition at line 172 of file LogCategory.cpp.

References folly::constexpr_clamp(), FLAG_INHERIT, getEffectiveLevel(), level_, folly::MAX_LEVEL, min, folly::MIN_LEVEL, parent_, uint32_t, and updateEffectiveLevel().

Referenced by getDB(), folly::LoggerDB::setLevel(), and folly::LoggerDB::updateConfig().

                                                             {
  // Clamp the value to MIN_LEVEL and MAX_LEVEL.
  //
  // This makes sure that UNINITIALIZED is always less than any valid level
  // value, and that level values cannot conflict with our flag bits.
  level = constexpr_clamp(level, LogLevel::MIN_LEVEL, LogLevel::MAX_LEVEL);

  // Make sure the inherit flag is always off for the root logger.
  if (!parent_) {
    inherit = false;
  }
  auto newValue = static_cast<uint32_t>(level);
  if (inherit) {
    newValue |= FLAG_INHERIT;
  }

  // Update the stored value
  uint32_t oldValue = level_.exchange(newValue, std::memory_order_acq_rel);

  // Break out early if the value has not changed.
  if (oldValue == newValue) {
    return;
  }

  // Update the effective log level
  LogLevel newEffectiveLevel;
  if (inherit) {
    newEffectiveLevel = std::min(level, parent_->getEffectiveLevel());
  } else {
    newEffectiveLevel = level;
  }
  updateEffectiveLevel(newEffectiveLevel);
}

void folly::LogCategory::updateEffectiveLevel ( LogLevel  newEffectiveLevel )

private

Definition at line 206 of file LogCategory.cpp.

References child, effectiveLevel_, firstChild_, nextSibling_, parentLevelUpdated(), and xlogLevels_.

Referenced by parentLevelUpdated(), and setLevelLocked().

                                                                 {
  auto oldEffectiveLevel =
      effectiveLevel_.exchange(newEffectiveLevel, std::memory_order_acq_rel);
  // Break out early if the value did not change.
  if (newEffectiveLevel == oldEffectiveLevel) {
    return;
  }

  // Update all of the values in xlogLevels_
  for (auto* levelPtr : xlogLevels_) {
    levelPtr->store(newEffectiveLevel, std::memory_order_release);
  }

  // Update all children loggers
  LogCategory* child = firstChild_;
  while (child != nullptr) {
    child->parentLevelUpdated(newEffectiveLevel);
    child = child->nextSibling_;
  }
}

void folly::LogCategory::updateHandlers

(

const std::unordered_map< std::shared_ptr< LogHandler >, std::shared_ptr< LogHandler >> &

handlerMap

)

Update the LogHandlers attached to this LogCategory by replacing currently attached handlers with new LogHandler objects.

The handlerMap argument is a map of (old_handler -> new_handler) If any of the LogHandlers currently attached to this category are found in the handlerMap, replace them with the new handler indicated in the map.

This is used when the LogHandler configuration is changed requiring one or more LogHandler objects to be replaced with new ones.

Definition at line 153 of file LogCategory.cpp.

References folly::get_ptr(), handlers_, and ptr.

Referenced by getDB().

                                                                         {
  auto handlers = handlers_.wlock();
  for (auto& entry : *handlers) {
    auto* ptr = get_ptr(handlerMap, entry);
    if (ptr) {
      entry = *ptr;
    }
  }
}

Member Data Documentation

LoggerDB* const folly::LogCategory::db_ {nullptr}

private

A pointer to the LoggerDB that we belong to.

This is almost always the main LoggerDB singleton. Unit tests are the main place where we use other LoggerDB objects besides the singleton.

Definition at line 280 of file LogCategory.h.

Referenced by admitMessage(), getDB(), LogCategory(), and setLevel().

std::atomic<LogLevel> folly::LogCategory::effectiveLevel_ {LogLevel::MAX_LEVEL}

private

The minimum log level of this category and all of its parents.

Definition at line 246 of file LogCategory.h.

Referenced by getEffectiveLevel(), getEffectiveLevelRelaxed(), logCheck(), and updateEffectiveLevel().

LogCategory* folly::LogCategory::firstChild_ {nullptr}

private

Pointers to children and sibling loggers. These pointers should only ever be accessed while holding the LoggerDB::loggersByName_ lock. (These are only modified when creating new loggers, which occurs with the main LoggerDB lock held.)

Definition at line 288 of file LogCategory.h.

Referenced by LogCategory(), and updateEffectiveLevel().

folly::Synchronized<std::vector<std::shared_ptr<LogHandler> > > folly::LogCategory::handlers_

private

The list of LogHandlers attached to this category.

Definition at line 272 of file LogCategory.h.

Referenced by addHandler(), clearHandlers(), getHandlers(), processMessage(), replaceHandlers(), and updateHandlers().

std::atomic<uint32_t> folly::LogCategory::level_ {0}

private

The current log level for this category.

The most significant bit is used to indicate if this logger should inherit its parent's effective log level.

Definition at line 254 of file LogCategory.h.

Referenced by getLevel(), getLevelInfo(), LogCategory(), parentLevelUpdated(), and setLevelLocked().

const std::string folly::LogCategory::name_

private

Our log category name.

Definition at line 267 of file LogCategory.h.

Referenced by getName(), LogCategory(), and processMessage().

LogCategory* folly::LogCategory::nextSibling_ {nullptr}

private

Definition at line 289 of file LogCategory.h.

Referenced by LogCategory(), and updateEffectiveLevel().

LogCategory* const folly::LogCategory::parent_ {nullptr}

private

Our parent LogCategory in the category hierarchy.

For instance, if our log name is "foo.bar.abc", our parent category is "foo.bar".

Definition at line 262 of file LogCategory.h.

Referenced by LogCategory(), processMessage(), and setLevelLocked().

std::vector<std::atomic<LogLevel>*> folly::LogCategory::xlogLevels_

private

A list of LogLevel values used by XLOG*() statements for this LogCategory. The XLOG*() statements will check these values. We ensure they are kept up-to-date each time the effective log level changes for this category.

This list may only be accessed while holding the main LoggerDB lock.

Definition at line 298 of file LogCategory.h.

Referenced by registerXlogLevel(), and updateEffectiveLevel().

---

The documentation for this class was generated from the following files:

• proxygen/folly/folly/logging/LogCategory.h
• proxygen/folly/folly/logging/LogCategory.cpp