globals.h (8316B)
1 // Copyright 2022 The Abseil Authors. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 // 15 // ----------------------------------------------------------------------------- 16 // File: log/globals.h 17 // ----------------------------------------------------------------------------- 18 // 19 // This header declares global logging library configuration knobs. 20 21 #ifndef ABSL_LOG_GLOBALS_H_ 22 #define ABSL_LOG_GLOBALS_H_ 23 24 #include "absl/base/attributes.h" 25 #include "absl/base/config.h" 26 #include "absl/base/log_severity.h" 27 #include "absl/log/internal/vlog_config.h" 28 #include "absl/strings/string_view.h" 29 30 namespace absl { 31 ABSL_NAMESPACE_BEGIN 32 33 //------------------------------------------------------------------------------ 34 // Minimum Log Level 35 //------------------------------------------------------------------------------ 36 // 37 // Messages logged at or above this severity are directed to all registered log 38 // sinks or skipped otherwise. This parameter can also be modified using 39 // command line flag --minloglevel. 40 // See absl/base/log_severity.h for descriptions of severity levels. 41 42 // MinLogLevel() 43 // 44 // Returns the value of the Minimum Log Level parameter. 45 // This function is async-signal-safe. 46 [[nodiscard]] absl::LogSeverityAtLeast MinLogLevel(); 47 48 // SetMinLogLevel() 49 // 50 // Updates the value of Minimum Log Level parameter. 51 // This function is async-signal-safe. 52 void SetMinLogLevel(absl::LogSeverityAtLeast severity); 53 54 namespace log_internal { 55 56 // ScopedMinLogLevel 57 // 58 // RAII type used to temporarily update the Min Log Level parameter. 59 class ScopedMinLogLevel final { 60 public: 61 explicit ScopedMinLogLevel(absl::LogSeverityAtLeast severity); 62 ScopedMinLogLevel(const ScopedMinLogLevel&) = delete; 63 ScopedMinLogLevel& operator=(const ScopedMinLogLevel&) = delete; 64 ~ScopedMinLogLevel(); 65 66 private: 67 absl::LogSeverityAtLeast saved_severity_; 68 }; 69 70 } // namespace log_internal 71 72 //------------------------------------------------------------------------------ 73 // Stderr Threshold 74 //------------------------------------------------------------------------------ 75 // 76 // Messages logged at or above this level are directed to stderr in 77 // addition to other registered log sinks. This parameter can also be modified 78 // using command line flag --stderrthreshold. 79 // See absl/base/log_severity.h for descriptions of severity levels. 80 81 // StderrThreshold() 82 // 83 // Returns the value of the Stderr Threshold parameter. 84 // This function is async-signal-safe. 85 [[nodiscard]] absl::LogSeverityAtLeast StderrThreshold(); 86 87 // SetStderrThreshold() 88 // 89 // Updates the Stderr Threshold parameter. 90 // This function is async-signal-safe. 91 void SetStderrThreshold(absl::LogSeverityAtLeast severity); 92 inline void SetStderrThreshold(absl::LogSeverity severity) { 93 absl::SetStderrThreshold(static_cast<absl::LogSeverityAtLeast>(severity)); 94 } 95 96 // ScopedStderrThreshold 97 // 98 // RAII type used to temporarily update the Stderr Threshold parameter. 99 class ScopedStderrThreshold final { 100 public: 101 explicit ScopedStderrThreshold(absl::LogSeverityAtLeast severity); 102 ScopedStderrThreshold(const ScopedStderrThreshold&) = delete; 103 ScopedStderrThreshold& operator=(const ScopedStderrThreshold&) = delete; 104 ~ScopedStderrThreshold(); 105 106 private: 107 absl::LogSeverityAtLeast saved_severity_; 108 }; 109 110 //------------------------------------------------------------------------------ 111 // Log Backtrace At 112 //------------------------------------------------------------------------------ 113 // 114 // Users can request an existing `LOG` statement, specified by file and line 115 // number, to also include a backtrace when logged. 116 117 // ShouldLogBacktraceAt() 118 // 119 // Returns true if we should log a backtrace at the specified location. 120 namespace log_internal { 121 [[nodiscard]] bool ShouldLogBacktraceAt(absl::string_view file, int line); 122 } // namespace log_internal 123 124 // SetLogBacktraceLocation() 125 // 126 // Sets the location the backtrace should be logged at. If the specified 127 // location isn't a `LOG` statement, the effect will be the same as 128 // `ClearLogBacktraceLocation` (but less efficient). 129 void SetLogBacktraceLocation(absl::string_view file, int line); 130 131 // ClearLogBacktraceLocation() 132 // 133 // Clears the set location so that backtraces will no longer be logged at it. 134 void ClearLogBacktraceLocation(); 135 136 //------------------------------------------------------------------------------ 137 // Prepend Log Prefix 138 //------------------------------------------------------------------------------ 139 // 140 // This option tells the logging library that every logged message 141 // should include the prefix (severity, date, time, PID, etc.) 142 // 143 // ShouldPrependLogPrefix() 144 // 145 // Returns the value of the Prepend Log Prefix option. 146 // This function is async-signal-safe. 147 [[nodiscard]] bool ShouldPrependLogPrefix(); 148 149 // EnableLogPrefix() 150 // 151 // Updates the value of the Prepend Log Prefix option. 152 // This function is async-signal-safe. 153 void EnableLogPrefix(bool on_off); 154 155 //------------------------------------------------------------------------------ 156 // `VLOG` Configuration 157 //------------------------------------------------------------------------------ 158 // 159 // These methods set the `(ABSL_)VLOG(_IS_ON)` threshold. They allow 160 // programmatic control of the thresholds set by the --v and --vmodule flags. 161 // 162 // Only `VLOG`s with a severity level LESS THAN OR EQUAL TO the threshold will 163 // be evaluated. 164 // 165 // For example, if the threshold is 2, then: 166 // 167 // VLOG(2) << "This message will be logged."; 168 // VLOG(3) << "This message will NOT be logged."; 169 // 170 // The default threshold is 0. Since `VLOG` levels must not be negative, a 171 // negative threshold value will turn off all VLOGs. 172 173 // SetGlobalVLogLevel() 174 // 175 // Sets the global `VLOG` level to threshold. Returns the previous global 176 // threshold. 177 inline int SetGlobalVLogLevel(int threshold) { 178 return absl::log_internal::UpdateGlobalVLogLevel(threshold); 179 } 180 181 // SetVLogLevel() 182 // 183 // Sets the `VLOG` threshold for all files that match `module_pattern`, 184 // overwriting any prior value. Files that don't match aren't affected. 185 // Returns the threshold that previously applied to `module_pattern`. 186 inline int SetVLogLevel(absl::string_view module_pattern, int threshold) { 187 return absl::log_internal::PrependVModule(module_pattern, threshold); 188 } 189 190 //------------------------------------------------------------------------------ 191 // Configure Android Native Log Tag 192 //------------------------------------------------------------------------------ 193 // 194 // The logging library forwards to the Android system log API when built for 195 // Android. That API takes a string "tag" value in addition to a message and 196 // severity level. The tag is used to identify the source of messages and to 197 // filter them. This library uses the tag "native" by default. 198 199 // SetAndroidNativeTag() 200 // 201 // Stores a copy of the string pointed to by `tag` and uses it as the Android 202 // logging tag thereafter. `tag` must not be null. 203 // This function must not be called more than once! 204 void SetAndroidNativeTag(const char* tag); 205 206 namespace log_internal { 207 // GetAndroidNativeTag() 208 // 209 // Returns the configured Android logging tag. 210 const char* GetAndroidNativeTag(); 211 } // namespace log_internal 212 213 namespace log_internal { 214 215 using LoggingGlobalsListener = void (*)(); 216 void SetLoggingGlobalsListener(LoggingGlobalsListener l); 217 218 // Internal implementation for the setter routines. These are used 219 // to break circular dependencies between flags and globals. Each "Raw" 220 // routine corresponds to the non-"Raw" counterpart and used to set the 221 // configuration parameter directly without calling back to the listener. 222 void RawSetMinLogLevel(absl::LogSeverityAtLeast severity); 223 void RawSetStderrThreshold(absl::LogSeverityAtLeast severity); 224 void RawEnableLogPrefix(bool on_off); 225 226 } // namespace log_internal 227 ABSL_NAMESPACE_END 228 } // namespace absl 229 230 #endif // ABSL_LOG_GLOBALS_H_