b1a1f249d233280493b9a63c209ab3fd3857e91f
[folly.git] / folly / experimental / logging / LoggerDB.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 <folly/Conv.h>
19 #include <folly/CppAttributes.h>
20 #include <folly/Range.h>
21 #include <folly/Synchronized.h>
22 #include <memory>
23 #include <string>
24 #include <unordered_map>
25 #include <vector>
26
27 #include <folly/experimental/logging/LogName.h>
28
29 namespace folly {
30
31 class LogCategory;
32 enum class LogLevel : uint32_t;
33
34 /**
35  * LoggerDB stores the set of LogCategory objects.
36  */
37 class LoggerDB {
38  public:
39   /**
40    * Get the main LoggerDB singleton.
41    */
42   static LoggerDB* get();
43
44   /**
45    * Get the LogCategory for the specified name.
46    *
47    * This creates the LogCategory for the specified name if it does not exist
48    * already.
49    */
50   LogCategory* getCategory(folly::StringPiece name);
51
52   /**
53    * Get the LogCategory for the specified name, if it already exists.
54    *
55    * This returns nullptr if no LogCategory has been created yet for the
56    * specified name.
57    */
58   LogCategory* FOLLY_NULLABLE getCategoryOrNull(folly::StringPiece name);
59
60   /**
61    * Set the log level for the specified category.
62    *
63    * Messages logged to a specific log category will be ignored unless the
64    * message log level is greater than the LogCategory's effective log level.
65    *
66    * If inherit is true, LogCategory's effective log level is the minimum of
67    * its level and it's parent category's effective log level.  If inherit is
68    * false, the LogCategory's effective log level is simply its log level.
69    * (Setting inherit to false is necessary if you want a child LogCategory to
70    * use a less verbose level than its parent categories.)
71    */
72   void setLevel(folly::StringPiece name, LogLevel level, bool inherit = true);
73   void setLevel(LogCategory* category, LogLevel level, bool inherit = true);
74
75   /**
76    * Apply a configuration string specifying a series a log levels.
77    *
78    * The string format is a comma separated list of <name>=<level> sections.
79    * e.g.: "foo=DBG3,log.bar=WARN"
80    *
81    * Returns a list of error messages for each error encountered trying to
82    * parse the config string.  The return value will be an empty vector if no
83    * errors were encountered.
84    */
85   std::vector<std::string> processConfigString(folly::StringPiece config);
86
87   /**
88    * Remove all registered LogHandlers on all LogCategory objects.
89    *
90    * This is called on the main LoggerDB object during shutdown.
91    */
92   void cleanupHandlers();
93
94   /**
95    * Initialize the LogCategory* and std::atomic<LogLevel> used by an XLOG()
96    * statement.
97    *
98    * Returns the current effective LogLevel of the category.
99    */
100   LogLevel xlogInit(
101       folly::StringPiece categoryName,
102       std::atomic<LogLevel>* xlogCategoryLevel,
103       LogCategory** xlogCategory);
104   LogCategory* xlogInitCategory(
105       folly::StringPiece categoryName,
106       LogCategory** xlogCategory,
107       std::atomic<bool>* isInitialized);
108
109   enum TestConstructorArg { TESTING };
110
111   /**
112    * Construct a LoggerDB for testing purposes.
113    *
114    * Most callers should not need this function, and should use
115    * LoggerDB::get() to obtain the main LoggerDB singleton.  This function
116    * exists mainly to allow testing LoggerDB objects in unit tests.
117    * It requires an explicit argument just to prevent callers from calling it
118    * unintentionally.
119    */
120   explicit LoggerDB(TestConstructorArg);
121
122   /**
123    * internalWarning() is used to report a problem when something goes wrong
124    * internally in the logging library.
125    *
126    * We can't log these messages through the normal logging flow since logging
127    * itself has failed.
128    *
129    * Example scenarios where this is used:
130    * - We fail to write to a log file (for instance, when the disk is full)
131    * - A LogHandler throws an unexpected exception
132    */
133   template <typename... Args>
134   static void internalWarning(
135       folly::StringPiece file,
136       int lineNumber,
137       Args&&... args) noexcept {
138     internalWarningImpl(
139         file, lineNumber, folly::to<std::string>(std::forward<Args>(args)...));
140   }
141
142   using InternalWarningHandler =
143       void (*)(folly::StringPiece file, int lineNumber, std::string&&);
144
145   /**
146    * Set a function to be called when the logging library generates an internal
147    * warning.
148    *
149    * The supplied handler should never throw exceptions.
150    *
151    * If a null handler is supplied, the default built-in handler will be used.
152    *
153    * The default handler reports the message with _CrtDbgReport(_CRT_WARN) on
154    * Windows, and prints the message to stderr on other platforms.  It also
155    * rate limits messages if they are arriving too quickly.
156    */
157   static void setInternalWarningHandler(InternalWarningHandler handler);
158
159  private:
160   using LoggerNameMap = std::unordered_map<
161       folly::StringPiece,
162       std::unique_ptr<LogCategory>,
163       LogName::Hash,
164       LogName::Equals>;
165
166   // Forbidden copy constructor and assignment operator
167   LoggerDB(LoggerDB const&) = delete;
168   LoggerDB& operator=(LoggerDB const&) = delete;
169
170   LoggerDB();
171   LogCategory* getOrCreateCategoryLocked(
172       LoggerNameMap& loggersByName,
173       folly::StringPiece name);
174   LogCategory* createCategoryLocked(
175       LoggerNameMap& loggersByName,
176       folly::StringPiece name,
177       LogCategory* parent);
178
179   static void internalWarningImpl(
180       folly::StringPiece filename,
181       int lineNumber,
182       std::string&& msg) noexcept;
183   static void defaultInternalWarningImpl(
184       folly::StringPiece filename,
185       int lineNumber,
186       std::string&& msg) noexcept;
187
188   /**
189    * A map of LogCategory objects by name.
190    *
191    * Lookups can be performed using arbitrary StringPiece values that do not
192    * have to be in canonical form.
193    */
194   folly::Synchronized<LoggerNameMap> loggersByName_;
195
196   static std::atomic<InternalWarningHandler> warningHandler_;
197 };
198 }