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 60 namespace rtc { 61 62 class 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 79 struct 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 84 const char * FindLabel(int value, const ConstantLabel entries[]); 85 std::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. 99 enum 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. 105 enum 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 117 class 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 235 class 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. 245 void LogMultiline(LoggingSeverity level, const char* label, bool input, 246 const void* data, size_t len, bool hex_mode, 247 LogMultilineState* state); 248 249 ////////////////////////////////////////////////////////////////////// 250 // Macros which automatically disable logging when LOGGING == 0 251 ////////////////////////////////////////////////////////////////////// 252 253 // If LOGGING is not explicitly defined, default to enabled in debug mode 254 #if !defined(LOGGING) 255 #if defined(_DEBUG) && !defined(NDEBUG) 256 #define LOGGING 1 257 #else 258 #define LOGGING 0 259 #endif 260 #endif // !defined(LOGGING) 261 262 #ifndef LOG 263 #if LOGGING 264 265 // The following non-obvious technique for implementation of a 266 // conditional log stream was stolen from google3/base/logging.h. 267 268 // This class is used to explicitly ignore values in the conditional 269 // logging macros. This avoids compiler warnings like "value computed 270 // is not used" and "statement has no effect". 271 272 class LogMessageVoidify { 273 public: 274 LogMessageVoidify() { } 275 // This has to be an operator with a precedence lower than << but 276 // higher than ?: 277 void operator&(std::ostream&) { } 278 }; 279 280 #define LOG_SEVERITY_PRECONDITION(sev) \ 281 !(rtc::LogMessage::Loggable(sev)) \ 282 ? (void) 0 \ 283 : rtc::LogMessageVoidify() & 284 285 #define LOG(sev) \ 286 LOG_SEVERITY_PRECONDITION(rtc::sev) \ 287 rtc::LogMessage(__FILE__, __LINE__, rtc::sev).stream() 288 289 // The _V version is for when a variable is passed in. It doesn't do the 290 // namespace concatination. 291 #define LOG_V(sev) \ 292 LOG_SEVERITY_PRECONDITION(sev) \ 293 rtc::LogMessage(__FILE__, __LINE__, sev).stream() 294 295 // The _F version prefixes the message with the current function name. 296 #if (defined(__GNUC__) && defined(_DEBUG)) || defined(WANT_PRETTY_LOG_F) 297 #define LOG_F(sev) LOG(sev) << __PRETTY_FUNCTION__ << ": " 298 #define LOG_T_F(sev) LOG(sev) << this << ": " << __PRETTY_FUNCTION__ << ": " 299 #else 300 #define LOG_F(sev) LOG(sev) << __FUNCTION__ << ": " 301 #define LOG_T_F(sev) LOG(sev) << this << ": " << __FUNCTION__ << ": " 302 #endif 303 304 #define LOG_CHECK_LEVEL(sev) \ 305 rtc::LogCheckLevel(rtc::sev) 306 #define LOG_CHECK_LEVEL_V(sev) \ 307 rtc::LogCheckLevel(sev) 308 inline bool LogCheckLevel(LoggingSeverity sev) { 309 return (LogMessage::GetMinLogSeverity() <= sev); 310 } 311 312 #define LOG_E(sev, ctx, err, ...) \ 313 LOG_SEVERITY_PRECONDITION(rtc::sev) \ 314 rtc::LogMessage(__FILE__, __LINE__, rtc::sev, \ 315 rtc::ERRCTX_ ## ctx, err , ##__VA_ARGS__) \ 316 .stream() 317 318 #define LOG_T(sev) LOG(sev) << this << ": " 319 320 #else // !LOGGING 321 322 // Hopefully, the compiler will optimize away some of this code. 323 // Note: syntax of "1 ? (void)0 : LogMessage" was causing errors in g++, 324 // converted to "while (false)" 325 #define LOG(sev) \ 326 while (false)rtc:: LogMessage(NULL, 0, rtc::sev).stream() 327 #define LOG_V(sev) \ 328 while (false) rtc::LogMessage(NULL, 0, sev).stream() 329 #define LOG_F(sev) LOG(sev) << __FUNCTION__ << ": " 330 #define LOG_CHECK_LEVEL(sev) \ 331 false 332 #define LOG_CHECK_LEVEL_V(sev) \ 333 false 334 335 #define LOG_E(sev, ctx, err, ...) \ 336 while (false) rtc::LogMessage(__FILE__, __LINE__, rtc::sev, \ 337 rtc::ERRCTX_ ## ctx, err , ##__VA_ARGS__) \ 338 .stream() 339 340 #define LOG_T(sev) LOG(sev) << this << ": " 341 #define LOG_T_F(sev) LOG(sev) << this << ": " << __FUNCTION__ << 342 #endif // !LOGGING 343 344 #define LOG_ERRNO_EX(sev, err) \ 345 LOG_E(sev, ERRNO, err) 346 #define LOG_ERRNO(sev) \ 347 LOG_ERRNO_EX(sev, errno) 348 349 #if defined(WEBRTC_WIN) 350 #define LOG_GLE_EX(sev, err) \ 351 LOG_E(sev, HRESULT, err) 352 #define LOG_GLE(sev) \ 353 LOG_GLE_EX(sev, GetLastError()) 354 #define LOG_GLEM(sev, mod) \ 355 LOG_E(sev, HRESULT, GetLastError(), mod) 356 #define LOG_ERR_EX(sev, err) \ 357 LOG_GLE_EX(sev, err) 358 #define LOG_ERR(sev) \ 359 LOG_GLE(sev) 360 #define LAST_SYSTEM_ERROR \ 361 (::GetLastError()) 362 #elif __native_client__ 363 #define LOG_ERR_EX(sev, err) \ 364 LOG(sev) 365 #define LOG_ERR(sev) \ 366 LOG(sev) 367 #define LAST_SYSTEM_ERROR \ 368 (0) 369 #elif defined(WEBRTC_POSIX) 370 #define LOG_ERR_EX(sev, err) \ 371 LOG_ERRNO_EX(sev, err) 372 #define LOG_ERR(sev) \ 373 LOG_ERRNO(sev) 374 #define LAST_SYSTEM_ERROR \ 375 (errno) 376 #endif // WEBRTC_WIN 377 378 #define PLOG(sev, err) \ 379 LOG_ERR_EX(sev, err) 380 381 // TODO(?): Add an "assert" wrapper that logs in the same manner. 382 383 #endif // LOG 384 385 } // namespace rtc 386 387 #endif // WEBRTC_BASE_LOGGING_H_ 388