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 "chromeos/chromeos_export.h"
  13
  14 namespace chromeos {
  15
  16 // These macros can be used to log chromeos 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(::chromeos::device_event_log::LOG_TYPE_NETWORK, \
  28              ::chromeos::device_event_log::LOG_LEVEL_##level)
  29 #define POWER_LOG(level)                                   \
  30   DEVICE_LOG(::chromeos::device_event_log::LOG_TYPE_POWER, \
  31              ::chromeos::device_event_log::LOG_LEVEL_##level)
  32 #define LOGIN_LOG(level)                                   \
  33   DEVICE_LOG(::chromeos::device_event_log::LOG_TYPE_LOGIN, \
  34              ::chromeos::device_event_log::LOG_LEVEL_##level)
  35
  36 // Generally prefer the above macros unless |level| is not constant.
  37
  38 #define DEVICE_LOG(type, level)                                   \
  39   ::chromeos::device_event_log::internal::DeviceEventLogInstance( \
  40       __FILE__, __LINE__, type, level).stream()
  41
  42 namespace device_event_log {
  43
  44 // Used to specify the type of event. NOTE: Be sure to update LogTypeFromString
  45 // and GetLogTypeString when adding entries to this enum. Also consider
  46 // updating chrome://device-log (see device_log_ui.cc).
  47 enum LogType {
  48   // Shill / network configuration related events.
  49   LOG_TYPE_NETWORK,
  50   // Power manager related events.
  51   LOG_TYPE_POWER,
  52   // Login related events.
  53   LOG_TYPE_LOGIN,
  54   // Used internally
  55   LOG_TYPE_UNKNOWN
  56 };
  57
  58 // Used to specify the detail level for logging. In GetAsString, used to
  59 // specify the maximum detail level (i.e. EVENT will include USER and ERROR).
  60 // See top-level comment for guidelines for each type.
  61 enum LogLevel {
  62   LOG_LEVEL_ERROR = 0,
  63   LOG_LEVEL_USER = 1,
  64   LOG_LEVEL_EVENT = 2,
  65   LOG_LEVEL_DEBUG = 3
  66 };
  67
  68 // Used to specify which order to output event entries in GetAsString.
  69 enum StringOrder { OLDEST_FIRST, NEWEST_FIRST };
  70
  71 // Initializes / shuts down device event logging. If |max_entries| = 0 the
  72 // default value will be used.
  73 CHROMEOS_EXPORT void Initialize(size_t max_entries);
  74 CHROMEOS_EXPORT void Shutdown();
  75
  76 // If the global instance is initialized, adds an entry to it. Regardless of
  77 // whether the global instance was intitialzed, this logs the event to
  78 // LOG(ERROR) if |type| = ERROR or VLOG(1) otherwise.
  79 CHROMEOS_EXPORT void AddEntry(const char* file,
  80                               int line,
  81                               LogType type,
  82                               LogLevel level,
  83                               const std::string& event);
  84
  85 // For backwards compatibility with network_event_log. Combines |event| and
  86 // |description| and calls AddEntry().
  87 CHROMEOS_EXPORT void AddEntryWithDescription(const char* file,
  88                                              int line,
  89                                              LogType type,
  90                                              LogLevel level,
  91                                              const std::string& event,
  92                                              const std::string& description);
  93
  94 // Outputs the log to a formatted string.
  95 // |order| determines which order to output the events.
  96 // |format| is a comma-separated string that determines which elements to show.
  97 //  e.g. "time,desc". Note: order of the strings does not affect the output.
  98 //  "time" - Include a timestamp.
  99 //  "file" - Include file and line number.
 100 //  "type" - Include the event type.
 101 //  "html" - Include html tags.
 102 //  "json" - Return JSON format dictionaries containing entries for timestamp,
 103 //           level, type, file, and event.
 104 // |types| lists the types included in the output. Prepend "non-" to disclude
 105 //  a type. e.g. "network,login" or "non-network". Use an empty string for
 106 //  all types.
 107 // |max_level| determines the maximum log level to be included in the output.
 108 // |max_events| limits how many events are output if > 0, otherwise all events
 109 //  are included.
 110 CHROMEOS_EXPORT std::string GetAsString(StringOrder order,
 111                                         const std::string& format,
 112                                         const std::string& types,
 113                                         LogLevel max_level,
 114                                         size_t max_events);
 115
 116 CHROMEOS_EXPORT extern const LogLevel kDefaultLogLevel;
 117
 118 namespace internal {
 119
 120 class CHROMEOS_EXPORT DeviceEventLogInstance {
 121  public:
 122   DeviceEventLogInstance(const char* file,
 123                          int line,
 124                          device_event_log::LogType type,
 125                          device_event_log::LogLevel level);
 126   ~DeviceEventLogInstance();
 127
 128   std::ostream& stream() { return stream_; }
 129
 130  private:
 131   const char* file_;
 132   const int line_;
 133   device_event_log::LogType type_;
 134   device_event_log::LogLevel level_;
 135   std::ostringstream stream_;
 136
 137   DISALLOW_COPY_AND_ASSIGN(DeviceEventLogInstance);
 138 };
 139
 140 }  // namespace internal
 141
 142 }  // namespace device_event_log
 143
 144 }  // namespace chromeos
 145
 146 #endif  // CHROMEOS_DEVICE_EVENT_LOG_H_