folly/experimental/logging/LogHandler.h

   1 /*
   2  * Copyright 2017-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 LogHandlerConfig;
  26 class LogMessage;
  27
  28 /**
  29  * LogHandler represents a generic API for processing log messages.
  30  *
  31  * LogHandlers have an associated log level.  The LogHandler will discard any
  32  * messages below its log level.  This allows specific LogHandlers to perform
  33  * additional filtering of messages even if the messages were enabled at the
  34  * LogCategory level.  For instance, a single LogCategory may have two
  35  * LogHandlers attached, one that logs locally to a file, and one that sends
  36  * messages to a remote logging service.  The local LogHandler may be
  37  * configured to record all messages, but the remote LogHandler may want to
  38  * only process ERROR messages and above, even when debug logging is enabled
  39  * for this LogCategory.
  40  *
  41  * By default the LogHandler level is set to LogLevel::NONE, which means that
  42  * all log messages will be processed.
  43  */
  44 class LogHandler {
  45  public:
  46   virtual ~LogHandler() = default;
  47
  48   /**
  49    * handleMessage() is called when a log message is processed by a LogCategory
  50    * that this handler is attached to.
  51    *
  52    * This must be implemented by LogHandler subclasses.
  53    *
  54    * handleMessage() will always be invoked from the thread that logged the
  55    * message.  LogMessage::getThreadID() contains the thread ID, but the
  56    * LogHandler can also include any other thread-local state they desire, and
  57    * this will always be data for the thread that originated the log message.
  58    *
  59    * @param message The LogMessage objet.
  60    * @param handlerCategory  The LogCategory that invoked handleMessage().
  61    *     This is the category that this LogHandler is attached to.  Note that
  62    *     this may be different than the category that this message was
  63    *     originally logged at.  message->getCategory() returns the category of
  64    *     the log message.
  65    */
  66   virtual void handleMessage(
  67       const LogMessage& message,
  68       const LogCategory* handlerCategory) = 0;
  69
  70   /**
  71    * Block until all messages that have already been sent to this LogHandler
  72    * have been processed.
  73    *
  74    * For LogHandlers that perform asynchronous processing of log messages,
  75    * this ensures that messages already sent to this handler have finished
  76    * being processed.
  77    *
  78    * Other threads may still call handleMessage() while flush() is running.
  79    * handleMessage() calls that did not complete before the flush() call
  80    * started will not necessarily be processed by the flush call.
  81    */
  82   virtual void flush() = 0;
  83
  84   /**
  85    * Return a LogHandlerConfig object describing the configuration of this
  86    * LogHandler.
  87    */
  88   virtual LogHandlerConfig getConfig() const = 0;
  89 };
  90 } // namespace folly