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