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/timer/elapsed_timer.h"
  13 #include "components/device_event_log/device_event_log_export.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
  35 // Generally prefer the above macros unless |type| or  |level| is not constant.
  36
  37 #define DEVICE_LOG(type, level)                                            \
  38   ::device_event_log::internal::DeviceEventLogInstance(__FILE__, __LINE__, \
  39                                                        type, level).stream()
  40
  41 // Declare {Type_LOG_IF_SLOW() at the top of a method to log slow methods
  42 // where "slow" is defined by kSlowMethodThresholdMs in the .cc file.
  43 #define SCOPED_NET_LOG_IF_SLOW() \
  44   SCOPED_DEVICE_LOG_IF_SLOW(::device_event_log::LOG_TYPE_NETWORK)
  45
  46 // Generally prefer the above macros unless |type| is not constant.
  47
  48 #define SCOPED_DEVICE_LOG_IF_SLOW(type)               \
  49   ::device_event_log::internal::ScopedDeviceLogIfSlow \
  50       scoped_device_log_if_slow(type, __FILE__, __func__)
  51
  52 namespace device_event_log {
  53
  54 // Used to specify the type of event. NOTE: Be sure to update LogTypeFromString
  55 // and GetLogTypeString when adding entries to this enum. Also consider
  56 // updating chrome://device-log (see device_log_ui.cc).
  57 enum LogType {
  58   // Shill / network configuration related events.
  59   LOG_TYPE_NETWORK,
  60   // Power manager related events.
  61   LOG_TYPE_POWER,
  62   // Login related events.
  63   LOG_TYPE_LOGIN,
  64   // Used internally
  65   LOG_TYPE_UNKNOWN
  66 };
  67
  68 // Used to specify the detail level for logging. In GetAsString, used to
  69 // specify the maximum detail level (i.e. EVENT will include USER and ERROR).
  70 // See top-level comment for guidelines for each type.
  71 enum LogLevel {
  72   LOG_LEVEL_ERROR = 0,
  73   LOG_LEVEL_USER = 1,
  74   LOG_LEVEL_EVENT = 2,
  75   LOG_LEVEL_DEBUG = 3
  76 };
  77
  78 // Used to specify which order to output event entries in GetAsString.
  79 enum StringOrder { OLDEST_FIRST, NEWEST_FIRST };
  80
  81 // Initializes / shuts down device event logging. If |max_entries| = 0 the
  82 // default value will be used.
  83 DEVICE_EVENT_LOG_EXPORT void Initialize(size_t max_entries);
  84 DEVICE_EVENT_LOG_EXPORT void Shutdown();
  85
  86 // If the global instance is initialized, adds an entry to it. Regardless of
  87 // whether the global instance was intitialzed, this logs the event to
  88 // LOG(ERROR) if |type| = ERROR or VLOG(1) otherwise.
  89 DEVICE_EVENT_LOG_EXPORT void AddEntry(const char* file,
  90                                       int line,
  91                                       LogType type,
  92                                       LogLevel level,
  93                                       const std::string& event);
  94
  95 // For backwards compatibility with network_event_log. Combines |event| and
  96 // |description| and calls AddEntry().
  97 DEVICE_EVENT_LOG_EXPORT void AddEntryWithDescription(
  98     const char* file,
  99     int line,
 100     LogType type,
 101     LogLevel level,
 102     const std::string& event,
 103     const std::string& description);
 104
 105 // Outputs the log to a formatted string.
 106 // |order| determines which order to output the events.
 107 // |format| is a comma-separated string that determines which elements to show.
 108 //  e.g. "time,desc". Note: order of the strings does not affect the output.
 109 //  "time" - Include a timestamp.
 110 //  "file" - Include file and line number.
 111 //  "type" - Include the event type.
 112 //  "html" - Include html tags.
 113 //  "json" - Return JSON format dictionaries containing entries for timestamp,
 114 //           level, type, file, and event.
 115 // |types| lists the types included in the output. Prepend "non-" to disclude
 116 //  a type. e.g. "network,login" or "non-network". Use an empty string for
 117 //  all types.
 118 // |max_level| determines the maximum log level to be included in the output.
 119 // |max_events| limits how many events are output if > 0, otherwise all events
 120 //  are included.
 121 DEVICE_EVENT_LOG_EXPORT std::string GetAsString(StringOrder order,
 122                                                 const std::string& format,
 123                                                 const std::string& types,
 124                                                 LogLevel max_level,
 125                                                 size_t max_events);
 126
 127 DEVICE_EVENT_LOG_EXPORT extern const LogLevel kDefaultLogLevel;
 128
 129 namespace internal {
 130
 131 // Implementation class for DEVICE_LOG macros. Provides a stream for creating
 132 // a log string and adds the event using device_event_log::AddEntry on
 133 // destruction.
 134 class DEVICE_EVENT_LOG_EXPORT DeviceEventLogInstance {
 135  public:
 136   DeviceEventLogInstance(const char* file,
 137                          int line,
 138                          device_event_log::LogType type,
 139                          device_event_log::LogLevel level);
 140   ~DeviceEventLogInstance();
 141
 142   std::ostream& stream() { return stream_; }
 143
 144  private:
 145   const char* file_;
 146   const int line_;
 147   device_event_log::LogType type_;
 148   device_event_log::LogLevel level_;
 149   std::ostringstream stream_;
 150
 151   DISALLOW_COPY_AND_ASSIGN(DeviceEventLogInstance);
 152 };
 153
 154 // Implementation class for SCOPED_LOG_IF_SLOW macros. Tests the elapsed time on
 155 // destruction and adds a Debug or Error log entry if it exceeds the
 156 // corresponding expected maximum elapsed time.
 157 class DEVICE_EVENT_LOG_EXPORT ScopedDeviceLogIfSlow {
 158  public:
 159   ScopedDeviceLogIfSlow(LogType type,
 160                         const char* file,
 161                         const std::string& name);
 162   ~ScopedDeviceLogIfSlow();
 163
 164  private:
 165   const char* file_;
 166   LogType type_;
 167   std::string name_;
 168   base::ElapsedTimer timer_;
 169 };
 170
 171 }  // namespace internal
 172
 173 }  // namespace device_event_log
 174
 175 #endif  // DEVICE_EVENT_LOG_DEVICE_EVENT_LOG_H_