henrike@webrtc.org | f7795df | 2014-05-13 18:00:26 +0000 | [diff] [blame^] | 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_ |