1/*
2 *  Copyright 2004 The WebRTC Project Authors. All rights reserved.
3 *
4 *  Use of this source code is governed by a BSD-style license
5 *  that can be found in the LICENSE file in the root of the source
6 *  tree. An additional intellectual property rights grant can be found
7 *  in the file PATENTS.  All contributing project authors may
8 *  be found in the AUTHORS file in the root of the source tree.
9 */
10
11//   LOG(...) an ostream target that can be used to send formatted
12// output to a variety of logging targets, such as debugger console, stderr,
13// file, or any StreamInterface.
14//   The severity level passed as the first argument to the LOGging
15// functions is used as a filter, to limit the verbosity of the logging.
16//   Static members of LogMessage documented below are used to control the
17// verbosity and target of the output.
18//   There are several variations on the LOG macro which facilitate logging
19// of common error conditions, detailed below.
20
21// LOG(sev) logs the given stream at severity "sev", which must be a
22//     compile-time constant of the LoggingSeverity type, without the namespace
23//     prefix.
24// LOG_V(sev) Like LOG(), but sev is a run-time variable of the LoggingSeverity
25//     type (basically, it just doesn't prepend the namespace).
26// LOG_F(sev) Like LOG(), but includes the name of the current function.
27// LOG_T(sev) Like LOG(), but includes the this pointer.
28// LOG_T_F(sev) Like LOG_F(), but includes the this pointer.
29// LOG_GLE(M)(sev [, mod]) attempt to add a string description of the
30//     HRESULT returned by GetLastError.  The "M" variant allows searching of a
31//     DLL's string table for the error description.
32// LOG_ERRNO(sev) attempts to add a string description of an errno-derived
33//     error. errno and associated facilities exist on both Windows and POSIX,
34//     but on Windows they only apply to the C/C++ runtime.
35// LOG_ERR(sev) is an alias for the platform's normal error system, i.e. _GLE on
36//     Windows and _ERRNO on POSIX.
37// (The above three also all have _EX versions that let you specify the error
38// code, rather than using the last one.)
39// LOG_E(sev, ctx, err, ...) logs a detailed error interpreted using the
40//     specified context.
41// LOG_CHECK_LEVEL(sev) (and LOG_CHECK_LEVEL_V(sev)) can be used as a test
42//     before performing expensive or sensitive operations whose sole purpose is
43//     to output logging data at the desired level.
44// Lastly, PLOG(sev, err) is an alias for LOG_ERR_EX.
45
46#ifndef WEBRTC_BASE_LOGGING_H_
47#define WEBRTC_BASE_LOGGING_H_
48
49#ifdef HAVE_CONFIG_H
50#include "config.h"  // NOLINT
51#endif
52
53#include <list>
54#include <sstream>
55#include <string>
56#include <utility>
57#include "webrtc/base/basictypes.h"
58#include "webrtc/base/criticalsection.h"
59
60namespace rtc {
61
62class StreamInterface;
63
64///////////////////////////////////////////////////////////////////////////////
65// ConstantLabel can be used to easily generate string names from constant
66// values.  This can be useful for logging descriptive names of error messages.
67// Usage:
68//   const ConstantLabel LIBRARY_ERRORS[] = {
69//     KLABEL(SOME_ERROR),
70//     KLABEL(SOME_OTHER_ERROR),
71//     ...
72//     LASTLABEL
73//   }
74//
75//   int err = LibraryFunc();
76//   LOG(LS_ERROR) << "LibraryFunc returned: "
77//                 << ErrorName(err, LIBRARY_ERRORS);
78
79struct ConstantLabel { int value; const char * label; };
80#define KLABEL(x) { x, #x }
81#define TLABEL(x, y) { x, y }
82#define LASTLABEL { 0, 0 }
83
84const char * FindLabel(int value, const ConstantLabel entries[]);
85std::string ErrorName(int err, const ConstantLabel* err_table);
86
87//////////////////////////////////////////////////////////////////////
88
89// Note that the non-standard LoggingSeverity aliases exist because they are
90// still in broad use.  The meanings of the levels are:
91//  LS_SENSITIVE: Information which should only be logged with the consent
92//   of the user, due to privacy concerns.
93//  LS_VERBOSE: This level is for data which we do not want to appear in the
94//   normal debug log, but should appear in diagnostic logs.
95//  LS_INFO: Chatty level used in debugging for all sorts of things, the default
96//   in debug builds.
97//  LS_WARNING: Something that may warrant investigation.
98//  LS_ERROR: Something that should not have occurred.
99enum LoggingSeverity { LS_SENSITIVE, LS_VERBOSE, LS_INFO, LS_WARNING, LS_ERROR,
100                       INFO = LS_INFO,
101                       WARNING = LS_WARNING,
102                       LERROR = LS_ERROR };
103
104// LogErrorContext assists in interpreting the meaning of an error value.
105enum LogErrorContext {
106  ERRCTX_NONE,
107  ERRCTX_ERRNO,     // System-local errno
108  ERRCTX_HRESULT,   // Windows HRESULT
109  ERRCTX_OSSTATUS,  // MacOS OSStatus
110
111  // Abbreviations for LOG_E macro
112  ERRCTX_EN = ERRCTX_ERRNO,     // LOG_E(sev, EN, x)
113  ERRCTX_HR = ERRCTX_HRESULT,   // LOG_E(sev, HR, x)
114  ERRCTX_OS = ERRCTX_OSSTATUS,  // LOG_E(sev, OS, x)
115};
116
117class LogMessage {
118 public:
119  static const int NO_LOGGING;
120  static const uint32 WARN_SLOW_LOGS_DELAY = 50;  // ms
121
122  LogMessage(const char* file, int line, LoggingSeverity sev,
123             LogErrorContext err_ctx = ERRCTX_NONE, int err = 0,
124             const char* module = NULL);
125  ~LogMessage();
126
127  static inline bool Loggable(LoggingSeverity sev) { return (sev >= min_sev_); }
128  std::ostream& stream() { return print_stream_; }
129
130  // Returns the time at which this function was called for the first time.
131  // The time will be used as the logging start time.
132  // If this is not called externally, the LogMessage ctor also calls it, in
133  // which case the logging start time will be the time of the first LogMessage
134  // instance is created.
135  static uint32 LogStartTime();
136
137  // Returns the wall clock equivalent of |LogStartTime|, in seconds from the
138  // epoch.
139  static uint32 WallClockStartTime();
140
141  // These are attributes which apply to all logging channels
142  //  LogContext: Display the file and line number of the message
143  static void LogContext(int min_sev);
144  //  LogThreads: Display the thread identifier of the current thread
145  static void LogThreads(bool on = true);
146  //  LogTimestamps: Display the elapsed time of the program
147  static void LogTimestamps(bool on = true);
148
149  // These are the available logging channels
150  //  Debug: Debug console on Windows, otherwise stderr
151  static void LogToDebug(int min_sev);
152  static int GetLogToDebug() { return dbg_sev_; }
153
154  //  Stream: Any non-blocking stream interface.  LogMessage takes ownership of
155  //   the stream. Multiple streams may be specified by using AddLogToStream.
156  //   LogToStream is retained for backwards compatibility; when invoked, it
157  //   will discard any previously set streams and install the specified stream.
158  //   GetLogToStream gets the severity for the specified stream, of if none
159  //   is specified, the minimum stream severity.
160  //   RemoveLogToStream removes the specified stream, without destroying it.
161  static void LogToStream(StreamInterface* stream, int min_sev);
162  static int GetLogToStream(StreamInterface* stream = NULL);
163  static void AddLogToStream(StreamInterface* stream, int min_sev);
164  static void RemoveLogToStream(StreamInterface* stream);
165
166  // Testing against MinLogSeverity allows code to avoid potentially expensive
167  // logging operations by pre-checking the logging level.
168  static int GetMinLogSeverity() { return min_sev_; }
169
170  static void SetDiagnosticMode(bool f) { is_diagnostic_mode_ = f; }
171  static bool IsDiagnosticMode() { return is_diagnostic_mode_; }
172
173  // Parses the provided parameter stream to configure the options above.
174  // Useful for configuring logging from the command line.  If file logging
175  // is enabled, it is output to the specified filename.
176  static void ConfigureLogging(const char* params, const char* filename);
177
178  // Convert the string to a LS_ value; also accept numeric values.
179  static int ParseLogSeverity(const std::string& value);
180
181 private:
182  typedef std::list<std::pair<StreamInterface*, int> > StreamList;
183
184  // Updates min_sev_ appropriately when debug sinks change.
185  static void UpdateMinLogSeverity();
186
187  // These assist in formatting some parts of the debug output.
188  static const char* Describe(LoggingSeverity sev);
189  static const char* DescribeFile(const char* file);
190
191  // These write out the actual log messages.
192  static void OutputToDebug(const std::string& msg, LoggingSeverity severity_);
193  static void OutputToStream(StreamInterface* stream, const std::string& msg);
194
195  // The ostream that buffers the formatted message before output
196  std::ostringstream print_stream_;
197
198  // The severity level of this message
199  LoggingSeverity severity_;
200
201  // String data generated in the constructor, that should be appended to
202  // the message before output.
203  std::string extra_;
204
205  // If time it takes to write to stream is more than this, log one
206  // additional warning about it.
207  uint32 warn_slow_logs_delay_;
208
209  // Global lock for the logging subsystem
210  static CriticalSection crit_;
211
212  // dbg_sev_ is the thresholds for those output targets
213  // min_sev_ is the minimum (most verbose) of those levels, and is used
214  //  as a short-circuit in the logging macros to identify messages that won't
215  //  be logged.
216  // ctx_sev_ is the minimum level at which file context is displayed
217  static int min_sev_, dbg_sev_, ctx_sev_;
218
219  // The output streams and their associated severities
220  static StreamList streams_;
221
222  // Flags for formatting options
223  static bool thread_, timestamp_;
224
225  // are we in diagnostic mode (as defined by the app)?
226  static bool is_diagnostic_mode_;
227
228  DISALLOW_EVIL_CONSTRUCTORS(LogMessage);
229};
230
231//////////////////////////////////////////////////////////////////////
232// Logging Helpers
233//////////////////////////////////////////////////////////////////////
234
235class LogMultilineState {
236 public:
237  size_t unprintable_count_[2];
238  LogMultilineState() {
239    unprintable_count_[0] = unprintable_count_[1] = 0;
240  }
241};
242
243// When possible, pass optional state variable to track various data across
244// multiple calls to LogMultiline.  Otherwise, pass NULL.
245void LogMultiline(LoggingSeverity level, const char* label, bool input,
246                  const void* data, size_t len, bool hex_mode,
247                  LogMultilineState* state);
248
249#ifndef LOG
250
251// The following non-obvious technique for implementation of a
252// conditional log stream was stolen from google3/base/logging.h.
253
254// This class is used to explicitly ignore values in the conditional
255// logging macros.  This avoids compiler warnings like "value computed
256// is not used" and "statement has no effect".
257
258class LogMessageVoidify {
259 public:
260  LogMessageVoidify() { }
261  // This has to be an operator with a precedence lower than << but
262  // higher than ?:
263  void operator&(std::ostream&) { }
264};
265
266#define LOG_SEVERITY_PRECONDITION(sev) \
267  !(rtc::LogMessage::Loggable(sev)) \
268    ? (void) 0 \
269    : rtc::LogMessageVoidify() &
270
271#define LOG(sev) \
272  LOG_SEVERITY_PRECONDITION(rtc::sev) \
273    rtc::LogMessage(__FILE__, __LINE__, rtc::sev).stream()
274
275// The _V version is for when a variable is passed in.  It doesn't do the
276// namespace concatination.
277#define LOG_V(sev) \
278  LOG_SEVERITY_PRECONDITION(sev) \
279    rtc::LogMessage(__FILE__, __LINE__, sev).stream()
280
281// The _F version prefixes the message with the current function name.
282#if (defined(__GNUC__) && defined(_DEBUG)) || defined(WANT_PRETTY_LOG_F)
283#define LOG_F(sev) LOG(sev) << __PRETTY_FUNCTION__ << ": "
284#define LOG_T_F(sev) LOG(sev) << this << ": " << __PRETTY_FUNCTION__ << ": "
285#else
286#define LOG_F(sev) LOG(sev) << __FUNCTION__ << ": "
287#define LOG_T_F(sev) LOG(sev) << this << ": " << __FUNCTION__ << ": "
288#endif
289
290#define LOG_CHECK_LEVEL(sev) \
291  rtc::LogCheckLevel(rtc::sev)
292#define LOG_CHECK_LEVEL_V(sev) \
293  rtc::LogCheckLevel(sev)
294inline bool LogCheckLevel(LoggingSeverity sev) {
295  return (LogMessage::GetMinLogSeverity() <= sev);
296}
297
298#define LOG_E(sev, ctx, err, ...) \
299  LOG_SEVERITY_PRECONDITION(rtc::sev) \
300    rtc::LogMessage(__FILE__, __LINE__, rtc::sev, \
301                          rtc::ERRCTX_ ## ctx, err , ##__VA_ARGS__) \
302        .stream()
303
304#define LOG_T(sev) LOG(sev) << this << ": "
305
306#define LOG_ERRNO_EX(sev, err) \
307  LOG_E(sev, ERRNO, err)
308#define LOG_ERRNO(sev) \
309  LOG_ERRNO_EX(sev, errno)
310
311#if defined(WEBRTC_WIN)
312#define LOG_GLE_EX(sev, err) \
313  LOG_E(sev, HRESULT, err)
314#define LOG_GLE(sev) \
315  LOG_GLE_EX(sev, GetLastError())
316#define LOG_GLEM(sev, mod) \
317  LOG_E(sev, HRESULT, GetLastError(), mod)
318#define LOG_ERR_EX(sev, err) \
319  LOG_GLE_EX(sev, err)
320#define LOG_ERR(sev) \
321  LOG_GLE(sev)
322#define LAST_SYSTEM_ERROR \
323  (::GetLastError())
324#elif __native_client__
325#define LOG_ERR_EX(sev, err) \
326  LOG(sev)
327#define LOG_ERR(sev) \
328  LOG(sev)
329#define LAST_SYSTEM_ERROR \
330  (0)
331#elif defined(WEBRTC_POSIX)
332#define LOG_ERR_EX(sev, err) \
333  LOG_ERRNO_EX(sev, err)
334#define LOG_ERR(sev) \
335  LOG_ERRNO(sev)
336#define LAST_SYSTEM_ERROR \
337  (errno)
338#endif  // WEBRTC_WIN
339
340#define PLOG(sev, err) \
341  LOG_ERR_EX(sev, err)
342
343// TODO(?): Add an "assert" wrapper that logs in the same manner.
344
345#endif  // LOG
346
347}  // namespace rtc
348
349#endif  // WEBRTC_BASE_LOGGING_H_
350