folly/experimental/logging/LogHandler.h

   1 /*
   2  * Copyright 2004-present Facebook, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *   http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16 #pragma once
  17
  18 #include <atomic>
  19
  20 #include <folly/experimental/logging/LogLevel.h>
  21
  22 namespace folly {
  23
  24 class LogCategory;
  25 class LogMessage;
  26
  27 /**
  28  * LogHandler represents a generic API for processing log messages.
  29  *
  30  * LogHandlers have an associated log level.  The LogHandler will discard any
  31  * messages below its log level.  This allows specific LogHandlers to perform
  32  * additional filtering of messages even if the messages were enabled at the
  33  * LogCategory level.  For instance, a single LogCategory may have two
  34  * LogHandlers attached, one that logs locally to a file, and one that sends
  35  * messages to a remote logging service.  The local LogHandler may be
  36  * configured to record all messages, but the remote LogHandler may want to
  37  * only process ERROR messages and above, even when debug logging is enabled
  38  * for this LogCategory.
  39  *
  40  * By default the LogHandler level is set to LogLevel::NONE, which means that
  41  * all log messages will be processed.
  42  */
  43 class LogHandler {
  44  public:
  45   virtual ~LogHandler() = default;
  46
  47   /**
  48    * handleMessage() is called when a log message is processed by a LogCategory
  49    * that this handler is attached to.
  50    *
  51    * This must be implemented by LogHandler subclasses.
  52    *
  53    * handleMessage() will always be invoked from the thread that logged the
  54    * message.  LogMessage::getThreadID() contains the thread ID, but the
  55    * LogHandler can also include any other thread-local state they desire, and
  56    * this will always be data for the thread that originated the log message.
  57    *
  58    * @param message The LogMessage objet.
  59    * @param handlerCategory  The LogCategory that invoked handleMessage().
  60    *     This is the category that this LogHandler is attached to.  Note that
  61    *     this may be different than the category that this message was
  62    *     originally logged at.  message->getCategory() returns the category of
  63    *     the log message.
  64    */
  65   virtual void handleMessage(
  66       const LogMessage& message,
  67       const LogCategory* handlerCategory) = 0;
  68
  69   /**
  70    * Block until all messages that have already been sent to this LogHandler
  71    * have been processed.
  72    *
  73    * For LogHandlers that perform asynchronous processing of log messages,
  74    * this ensures that messages already sent to this handler have finished
  75    * being processed.
  76    *
  77    * Other threads may still call handleMessage() while flush() is running.
  78    * handleMessage() calls that did not complete before the flush() call
  79    * started will not necessarily be processed by the flush call.
  80    */
  81   virtual void flush() = 0;
  82 };
  83 } // namespace folly