components/device_event_log/device_event_log.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef COMPONENTS_DEVICE_EVENT_LOG_DEVICE_EVENT_LOG_H_
   6 #define COMPONENTS_DEVICE_EVENT_LOG_DEVICE_EVENT_LOG_H_
   7
   8 #include <cstring>
   9 #include <sstream>
  10
  11 #include "base/basictypes.h"
  12 #include "base/logging.h"
  13 #include "base/timer/elapsed_timer.h"
  14 #include "components/device_event_log/device_event_log_export.h"
  15
  16 // These macros can be used to log device related events.
  17 //
  18 // NOTE: If these macros are called from a thread other than the thread that
  19 // device_event_log::Initialize() was called from (i.e. the UI thread), a task
  20 // will be posted to the UI thread to log the event.
  21 //
  22 // The following values should be used for |level| in these macros:
  23 //  ERROR Unexpected events, or device level failures. Use sparingly.
  24 //  USER  Events initiated directly by a user (or Chrome) action.
  25 //  EVENT Default event type.
  26 //  DEBUG Debugging details that are usually not interesting.
  27 //
  28 // Examples:
  29 //  NET_LOG(EVENT) << "NetworkState Changed " << name << ": " << state;
  30 //  POWER_LOG(USER) << "Suspend requested";
  31
  32 #define NET_LOG(level)                             \
  33   DEVICE_LOG(::device_event_log::LOG_TYPE_NETWORK, \
  34              ::device_event_log::LOG_LEVEL_##level)
  35 #define POWER_LOG(level)                         \
  36   DEVICE_LOG(::device_event_log::LOG_TYPE_POWER, \
  37              ::device_event_log::LOG_LEVEL_##level)
  38 #define LOGIN_LOG(level)                         \
  39   DEVICE_LOG(::device_event_log::LOG_TYPE_LOGIN, \
  40              ::device_event_log::LOG_LEVEL_##level)
  41 #define USB_LOG(level)                         \
  42   DEVICE_LOG(::device_event_log::LOG_TYPE_USB, \
  43              ::device_event_log::LOG_LEVEL_##level)
  44 #define USB_PLOG(level)                         \
  45   DEVICE_PLOG(::device_event_log::LOG_TYPE_USB, \
  46               ::device_event_log::LOG_LEVEL_##level)
  47 #define HID_LOG(level)                         \
  48   DEVICE_LOG(::device_event_log::LOG_TYPE_HID, \
  49              ::device_event_log::LOG_LEVEL_##level)
  50 #define HID_PLOG(level)                         \
  51   DEVICE_PLOG(::device_event_log::LOG_TYPE_HID, \
  52               ::device_event_log::LOG_LEVEL_##level)
  53
  54 // Generally prefer the above macros unless |type| or |level| is not constant.
  55
  56 #define DEVICE_LOG(type, level)                                            \
  57   ::device_event_log::internal::DeviceEventLogInstance(__FILE__, __LINE__, \
  58                                                        type, level).stream()
  59 #define DEVICE_PLOG(type, level)                                            \
  60   ::device_event_log::internal::DeviceEventSystemErrorLogInstance(          \
  61       __FILE__, __LINE__, type, level, ::logging::GetLastSystemErrorCode()) \
  62       .stream()
  63
  64 // Declare {Type_LOG_IF_SLOW() at the top of a method to log slow methods
  65 // where "slow" is defined by kSlowMethodThresholdMs in the .cc file.
  66 #define SCOPED_NET_LOG_IF_SLOW() \
  67   SCOPED_DEVICE_LOG_IF_SLOW(::device_event_log::LOG_TYPE_NETWORK)
  68
  69 // Generally prefer the above macros unless |type| is not constant.
  70
  71 #define SCOPED_DEVICE_LOG_IF_SLOW(type)               \
  72   ::device_event_log::internal::ScopedDeviceLogIfSlow \
  73       scoped_device_log_if_slow(type, __FILE__, __func__)
  74
  75 namespace device_event_log {
  76
  77 // Used to specify the type of event. NOTE: Be sure to update LogTypeFromString
  78 // and GetLogTypeString when adding entries to this enum. Also consider
  79 // updating chrome://device-log (see device_log_ui.cc).
  80 enum LogType {
  81   // Shill / network configuration related events.
  82   LOG_TYPE_NETWORK,
  83   // Power manager related events.
  84   LOG_TYPE_POWER,
  85   // Login related events.
  86   LOG_TYPE_LOGIN,
  87   // USB device related events (i.e. device/usb).
  88   LOG_TYPE_USB,
  89   // Human-interface device related events (i.e. device/hid).
  90   LOG_TYPE_HID,
  91   // Used internally
  92   LOG_TYPE_UNKNOWN
  93 };
  94
  95 // Used to specify the detail level for logging. In GetAsString, used to
  96 // specify the maximum detail level (i.e. EVENT will include USER and ERROR).
  97 // See top-level comment for guidelines for each type.
  98 enum LogLevel {
  99   LOG_LEVEL_ERROR = 0,
 100   LOG_LEVEL_USER = 1,
 101   LOG_LEVEL_EVENT = 2,
 102   LOG_LEVEL_DEBUG = 3
 103 };
 104
 105 // Used to specify which order to output event entries in GetAsString.
 106 enum StringOrder { OLDEST_FIRST, NEWEST_FIRST };
 107
 108 // Initializes / shuts down device event logging. If |max_entries| = 0 the
 109 // default value will be used.
 110 void DEVICE_EVENT_LOG_EXPORT Initialize(size_t max_entries);
 111 bool DEVICE_EVENT_LOG_EXPORT IsInitialized();
 112 void DEVICE_EVENT_LOG_EXPORT Shutdown();
 113
 114 // If the global instance is initialized, adds an entry to it. Regardless of
 115 // whether the global instance was intitialzed, this logs the event to
 116 // LOG(ERROR) if |type| = ERROR or VLOG(1) otherwise.
 117 void DEVICE_EVENT_LOG_EXPORT AddEntry(const char* file,
 118                                       int line,
 119                                       LogType type,
 120                                       LogLevel level,
 121                                       const std::string& event);
 122
 123 // For backwards compatibility with network_event_log. Combines |event| and
 124 // |description| and calls AddEntry().
 125 void DEVICE_EVENT_LOG_EXPORT
 126 AddEntryWithDescription(const char* file,
 127                         int line,
 128                         LogType type,
 129                         LogLevel level,
 130                         const std::string& event,
 131                         const std::string& description);
 132
 133 // Outputs the log to a formatted string.
 134 // |order| determines which order to output the events.
 135 // |format| is a comma-separated string that determines which elements to show.
 136 //  e.g. "time,desc". Note: order of the strings does not affect the output.
 137 //  "time" - Include a timestamp.
 138 //  "file" - Include file and line number.
 139 //  "type" - Include the event type.
 140 //  "html" - Include html tags.
 141 //  "json" - Return JSON format dictionaries containing entries for timestamp,
 142 //           level, type, file, and event.
 143 // |types| lists the types included in the output. Prepend "non-" to disclude
 144 //  a type. e.g. "network,login" or "non-network". Use an empty string for
 145 //  all types.
 146 // |max_level| determines the maximum log level to be included in the output.
 147 // |max_events| limits how many events are output if > 0, otherwise all events
 148 //  are included.
 149 std::string DEVICE_EVENT_LOG_EXPORT GetAsString(StringOrder order,
 150                                                 const std::string& format,
 151                                                 const std::string& types,
 152                                                 LogLevel max_level,
 153                                                 size_t max_events);
 154
 155 DEVICE_EVENT_LOG_EXPORT extern const LogLevel kDefaultLogLevel;
 156
 157 namespace internal {
 158
 159 // Implementation class for DEVICE_LOG macros. Provides a stream for creating
 160 // a log string and adds the event using device_event_log::AddEntry on
 161 // destruction.
 162 class DEVICE_EVENT_LOG_EXPORT DeviceEventLogInstance {
 163  public:
 164   DeviceEventLogInstance(const char* file,
 165                          int line,
 166                          device_event_log::LogType type,
 167                          device_event_log::LogLevel level);
 168   ~DeviceEventLogInstance();
 169
 170   std::ostream& stream() { return stream_; }
 171
 172  private:
 173   const char* file_;
 174   const int line_;
 175   device_event_log::LogType type_;
 176   device_event_log::LogLevel level_;
 177   std::ostringstream stream_;
 178
 179   DISALLOW_COPY_AND_ASSIGN(DeviceEventLogInstance);
 180 };
 181
 182 // Implementation class for DEVICE_PLOG macros. Provides a stream for creating
 183 // a log string and adds the event, including system error code, using
 184 // device_event_log::AddEntry on destruction.
 185 class DEVICE_EVENT_LOG_EXPORT DeviceEventSystemErrorLogInstance {
 186  public:
 187   DeviceEventSystemErrorLogInstance(const char* file,
 188                                     int line,
 189                                     device_event_log::LogType type,
 190                                     device_event_log::LogLevel level,
 191                                     logging::SystemErrorCode err);
 192   ~DeviceEventSystemErrorLogInstance();
 193
 194   std::ostream& stream() { return log_instance_.stream(); }
 195
 196  private:
 197   logging::SystemErrorCode err_;
 198   // Constructor parameters are passed to |log_instance_| which will update the
 199   // log when it is destroyed (after a string description of |err_| is appended
 200   // to the stream).
 201   DeviceEventLogInstance log_instance_;
 202
 203   DISALLOW_COPY_AND_ASSIGN(DeviceEventSystemErrorLogInstance);
 204 };
 205
 206 // Implementation class for SCOPED_LOG_IF_SLOW macros. Tests the elapsed time on
 207 // destruction and adds a Debug or Error log entry if it exceeds the
 208 // corresponding expected maximum elapsed time.
 209 class DEVICE_EVENT_LOG_EXPORT ScopedDeviceLogIfSlow {
 210  public:
 211   ScopedDeviceLogIfSlow(LogType type,
 212                         const char* file,
 213                         const std::string& name);
 214   ~ScopedDeviceLogIfSlow();
 215
 216  private:
 217   const char* file_;
 218   LogType type_;
 219   std::string name_;
 220   base::ElapsedTimer timer_;
 221 };
 222
 223 }  // namespace internal
 224
 225 }  // namespace device_event_log
 226
 227 #endif  // DEVICE_EVENT_LOG_DEVICE_EVENT_LOG_H_