Home | History | Annotate | Download | only in base
      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 #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 
    258 class 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)
    294 inline 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