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/strings/string_view.h"
28
29 namespace absl {
30 ABSL_NAMESPACE_BEGIN
31
32 //------------------------------------------------------------------------------
33 // Minimum Log Level
34 //------------------------------------------------------------------------------
35 //
36 // Messages logged at or above this severity are directed to all registered log
37 // sinks or skipped otherwise. This parameter can also be modified using
38 // command line flag --minloglevel.
39 // See absl/base/log_severity.h for descriptions of severity levels.
40
41 // MinLogLevel()
42 //
43 // Returns the value of the Minimum Log Level parameter.
44 // This function is async-signal-safe.
45 ABSL_MUST_USE_RESULT absl::LogSeverityAtLeast MinLogLevel();
46
47 // SetMinLogLevel()
48 //
49 // Updates the value of Minimum Log Level parameter.
50 // This function is async-signal-safe.
51 void SetMinLogLevel(absl::LogSeverityAtLeast severity);
52
53 namespace log_internal {
54
55 // ScopedMinLogLevel
56 //
57 // RAII type used to temporarily update the Min Log Level parameter.
58 class ScopedMinLogLevel final {
59 public:
60 explicit ScopedMinLogLevel(absl::LogSeverityAtLeast severity);
61 ScopedMinLogLevel(const ScopedMinLogLevel&) = delete;
62 ScopedMinLogLevel& operator=(const ScopedMinLogLevel&) = delete;
63 ~ScopedMinLogLevel();
64
65 private:
66 absl::LogSeverityAtLeast saved_severity_;
67 };
68
69 } // namespace log_internal
70
71 //------------------------------------------------------------------------------
72 // Stderr Threshold
73 //------------------------------------------------------------------------------
74 //
75 // Messages logged at or above this level are directed to stderr in
76 // addition to other registered log sinks. This parameter can also be modified
77 // using command line flag --stderrthreshold.
78 // See absl/base/log_severity.h for descriptions of severity levels.
79
80 // StderrThreshold()
81 //
82 // Returns the value of the Stderr Threshold parameter.
83 // This function is async-signal-safe.
84 ABSL_MUST_USE_RESULT absl::LogSeverityAtLeast StderrThreshold();
85
86 // SetStderrThreshold()
87 //
88 // Updates the Stderr Threshold parameter.
89 // This function is async-signal-safe.
90 void SetStderrThreshold(absl::LogSeverityAtLeast severity);
SetStderrThreshold(absl::LogSeverity severity)91 inline void SetStderrThreshold(absl::LogSeverity severity) {
92 absl::SetStderrThreshold(static_cast<absl::LogSeverityAtLeast>(severity));
93 }
94
95 // ScopedStderrThreshold
96 //
97 // RAII type used to temporarily update the Stderr Threshold parameter.
98 class ScopedStderrThreshold final {
99 public:
100 explicit ScopedStderrThreshold(absl::LogSeverityAtLeast severity);
101 ScopedStderrThreshold(const ScopedStderrThreshold&) = delete;
102 ScopedStderrThreshold& operator=(const ScopedStderrThreshold&) = delete;
103 ~ScopedStderrThreshold();
104
105 private:
106 absl::LogSeverityAtLeast saved_severity_;
107 };
108
109 //------------------------------------------------------------------------------
110 // Log Backtrace At
111 //------------------------------------------------------------------------------
112 //
113 // Users can request an existing `LOG` statement, specified by file and line
114 // number, to also include a backtrace when logged.
115
116 // ShouldLogBacktraceAt()
117 //
118 // Returns true if we should log a backtrace at the specified location.
119 namespace log_internal {
120 ABSL_MUST_USE_RESULT bool ShouldLogBacktraceAt(absl::string_view file,
121 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 ABSL_MUST_USE_RESULT 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 // Configure Android Native Log Tag
157 //------------------------------------------------------------------------------
158 //
159 // The logging library forwards to the Android system log API when built for
160 // Android. That API takes a string "tag" value in addition to a message and
161 // severity level. The tag is used to identify the source of messages and to
162 // filter them. This library uses the tag "native" by default.
163
164 // SetAndroidNativeTag()
165 //
166 // Stores a copy of the string pointed to by `tag` and uses it as the Android
167 // logging tag thereafter. `tag` must not be null.
168 // This function must not be called more than once!
169 void SetAndroidNativeTag(const char* tag);
170
171 namespace log_internal {
172 // GetAndroidNativeTag()
173 //
174 // Returns the configured Android logging tag.
175 const char* GetAndroidNativeTag();
176 } // namespace log_internal
177
178 namespace log_internal {
179
180 using LoggingGlobalsListener = void (*)();
181 void SetLoggingGlobalsListener(LoggingGlobalsListener l);
182
183 // Internal implementation for the setter routines. These are used
184 // to break circular dependencies between flags and globals. Each "Raw"
185 // routine corresponds to the non-"Raw" counterpart and used to set the
186 // configuration parameter directly without calling back to the listener.
187 void RawSetMinLogLevel(absl::LogSeverityAtLeast severity);
188 void RawSetStderrThreshold(absl::LogSeverityAtLeast severity);
189 void RawEnableLogPrefix(bool on_off);
190
191 } // namespace log_internal
192 ABSL_NAMESPACE_END
193 } // namespace absl
194
195 #endif // ABSL_LOG_GLOBALS_H_
196