e589400e910f0ab0f8d460e463259f81679741b2
[folly.git] / folly / experimental / logging / LogCategory.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 #include <cstdint>
20 #include <list>
21 #include <string>
22
23 #include <folly/Range.h>
24 #include <folly/Synchronized.h>
25 #include <folly/experimental/logging/LogLevel.h>
26
27 namespace folly {
28
29 class LoggerDB;
30 class LogHandler;
31 class LogMessage;
32
33 /**
34  * LogCategory stores all of the logging configuration for a specific
35  * log category.
36  *
37  * This class is separate from Logger to allow multiple Logger objects to all
38  * refer to the same log category.  Logger can be thought of as a small wrapper
39  * class that behaves like a pointer to a LogCategory object.
40  */
41 class LogCategory {
42  public:
43   /**
44    * Create the root LogCategory.
45    *
46    * This should generally only be invoked by LoggerDB.
47    */
48   explicit LogCategory(LoggerDB* db);
49
50   /**
51    * Create a new LogCategory.
52    *
53    * This should only be invoked by LoggerDB, while holding the main LoggerDB
54    * lock.
55    *
56    * The name argument should already be in canonical form.
57    *
58    * This constructor automatically adds this new LogCategory to the parent
59    * category's firstChild_ linked-list.
60    */
61   LogCategory(folly::StringPiece name, LogCategory* parent);
62
63   /**
64    * Get the name of this log category.
65    */
66   const std::string& getName() const {
67     return name_;
68   }
69
70   /**
71    * Get the level for this log category.
72    */
73   LogLevel getLevel() const {
74     return static_cast<LogLevel>(
75         level_.load(std::memory_order_acquire) & ~FLAG_INHERIT);
76   }
77
78   /**
79    * Get the effective level for this log category.
80    *
81    * This is the minimum log level of this category and all of its parents.
82    * Log messages below this level will be ignored, while messages at or
83    * above this level need to be processed by this category or one of its
84    * parents.
85    */
86   LogLevel getEffectiveLevel() const {
87     return effectiveLevel_.load(std::memory_order_acquire);
88   }
89
90   /**
91    * Get the effective log level using std::memory_order_relaxed.
92    *
93    * This is primarily used for log message checks.  Most other callers should
94    * use getEffectiveLevel() above to be more conservative with regards to
95    * memory ordering.
96    */
97   LogLevel getEffectiveLevelRelaxed() const {
98     return effectiveLevel_.load(std::memory_order_relaxed);
99   }
100
101   /**
102    * Check whether this Logger or any of its parent Loggers would do anything
103    * with a log message at the given level.
104    */
105   bool logCheck(LogLevel level) const {
106     // We load the effective level using std::memory_order_relaxed.
107     //
108     // We want to make log checks as lightweight as possible.  It's fine if we
109     // don't immediately respond to changes made to the log level from other
110     // threads.  We can wait until some other operation triggers a memory
111     // barrier before we honor the new log level setting.  No other memory
112     // accesses depend on the log level value.  Callers should not rely on all
113     // other threads to immediately stop logging as soon as they decrease the
114     // log level for a given category.
115     return effectiveLevel_.load(std::memory_order_relaxed) <= level;
116   }
117
118   /**
119    * Set the log level for this LogCategory.
120    *
121    * Messages logged to a specific log category will be ignored unless the
122    * message log level is greater than the LogCategory's effective log level.
123    *
124    * If inherit is true, LogCategory's effective log level is the minimum of
125    * its level and its parent category's effective log level.  If inherit is
126    * false, the LogCategory's effective log level is simply its log level.
127    * (Setting inherit to false is necessary if you want a child LogCategory to
128    * use a less verbose level than its parent categories.)
129    */
130   void setLevel(LogLevel level, bool inherit = true);
131
132   /**
133    * Get the LoggerDB that this LogCategory belongs to.
134    *
135    * This is almost always the main LoggerDB singleton returned by
136    * LoggerDB::get().  The logging unit tests are the main location that
137    * creates alternative LoggerDB objects.
138    */
139   LoggerDB* getDB() const {
140     return db_;
141   }
142
143   /**
144    * Attach a LogHandler to this category.
145    */
146   void addHandler(std::shared_ptr<LogHandler> handler);
147
148   /**
149    * Remove all LogHandlers from this category.
150    */
151   void clearHandlers();
152
153   /* Internal methods for use by other parts of the logging library code */
154
155   /**
156    * Process a log message.
157    *
158    * This method generally should be invoked only through the logging macros,
159    * rather than calling this directly.
160    *
161    * This method assumes that log level admittance checks have already been
162    * performed.  This method unconditionally passes the message to the
163    * LogHandlers attached to this LogCategory, without any additional log level
164    * checks (apart from the ones done in the LogHandlers).
165    */
166   void processMessage(const LogMessage& message) const;
167
168   /**
169    * Note: setLevelLocked() may only be called while holding the main
170    * LoggerDB lock.
171    *
172    * This method should only be invoked by LoggerDB.
173    */
174   void setLevelLocked(LogLevel level, bool inherit);
175
176   /**
177    * Register a std::atomic<LogLevel> value used by XLOG*() macros to check the
178    * effective level for this category.
179    *
180    * The LogCategory will keep this value updated whenever its effective log
181    * level changes.
182    *
183    * This function should only be invoked by LoggerDB, and the LoggerDB lock
184    * must be held when calling it.
185    */
186   void registerXlogLevel(std::atomic<LogLevel>* levelPtr);
187
188  private:
189   enum : uint32_t { FLAG_INHERIT = 0x80000000 };
190
191   // Forbidden copy constructor and assignment operator
192   LogCategory(LogCategory const&) = delete;
193   LogCategory& operator=(LogCategory const&) = delete;
194
195   void updateEffectiveLevel(LogLevel newEffectiveLevel);
196   void parentLevelUpdated(LogLevel parentEffectiveLevel);
197
198   /**
199    * The minimum log level of this category and all of its parents.
200    */
201   std::atomic<LogLevel> effectiveLevel_{LogLevel::MAX_LEVEL};
202
203   /**
204    * The current log level for this category.
205    *
206    * The most significant bit is used to indicate if this logger should
207    * inherit its parent's effective log level.
208    */
209   std::atomic<uint32_t> level_{0};
210
211   /**
212    * Our parent LogCategory in the category hierarchy.
213    *
214    * For instance, if our log name is "foo.bar.abc", our parent category
215    * is "foo.bar".
216    */
217   LogCategory* const parent_{nullptr};
218
219   /**
220    * Our log category name.
221    */
222   const std::string name_;
223
224   /**
225    * The list of LogHandlers attached to this category.
226    */
227   folly::Synchronized<std::vector<std::shared_ptr<LogHandler>>> handlers_;
228
229   /**
230    * A pointer to the LoggerDB that we belong to.
231    *
232    * This is almost always the main LoggerDB singleton.  Unit tests are the
233    * main place where we use other LoggerDB objects besides the singleton.
234    */
235   LoggerDB* const db_{nullptr};
236
237   /**
238    * Pointers to children and sibling loggers.
239    * These pointers should only ever be accessed while holding the main
240    * LoggerDB lock.  (These are only modified when creating new loggers,
241    * which occurs with the main LoggerDB lock held.)
242    */
243   LogCategory* firstChild_{nullptr};
244   LogCategory* nextSibling_{nullptr};
245
246   /**
247    * A list of LogLevel values used by XLOG*() statements for this LogCategory.
248    * The XLOG*() statements will check these values.  We ensure they are kept
249    * up-to-date each time the effective log level changes for this category.
250    *
251    * This list may only be accessed while holding the main LoggerDB lock.
252    */
253   std::vector<std::atomic<LogLevel>*> xlogLevels_;
254 };
255 }