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