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