chromeos/network/network_event_log.h

   1 // Copyright (c) 2012 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_NETWORK_NETWORK_EVENT_LOG_H_
   6 #define CHROMEOS_NETWORK_NETWORK_EVENT_LOG_H_
   7
   8 #include <deque>
   9 #include <string>
  10
  11 #include "base/basictypes.h"
  12 #include "base/strings/stringprintf.h"
  13 #include "base/time/time.h"
  14 #include "chromeos/chromeos_export.h"
  15
  16 namespace base {
  17 class Value;
  18 }
  19
  20 namespace chromeos {
  21
  22 // Namespace for functions for logging network events.
  23 namespace network_event_log {
  24
  25 // Used to determine which order to output event entries in GetAsString.
  26 enum StringOrder {
  27   OLDEST_FIRST,
  28   NEWEST_FIRST
  29 };
  30
  31 // Used to set the detail level for logging.
  32 enum LogLevel {
  33   LOG_LEVEL_ERROR = 0,
  34   LOG_LEVEL_USER = 1,
  35   LOG_LEVEL_EVENT = 2,
  36   LOG_LEVEL_DEBUG = 3
  37 };
  38
  39 // Default log level.
  40 CHROMEOS_EXPORT extern const LogLevel kDefaultLogLevel;
  41
  42 // Initializes / shuts down network event logging. Calling Initialize more than
  43 // once will reset the log.
  44 CHROMEOS_EXPORT void Initialize();
  45 CHROMEOS_EXPORT void Shutdown();
  46
  47 // Returns true if network event logging has been initialized.
  48 CHROMEOS_EXPORT bool IsInitialized();
  49
  50 namespace internal {
  51
  52 // Gets the maximum number of log entries.
  53 CHROMEOS_EXPORT size_t GetMaxLogEntries();
  54
  55 // Sets the maximum number of entries to something other than the default. If
  56 // |max_entries| is less than the current maximum number of entries, this will
  57 // delete any existing entries in excess of |max_entries|.
  58 CHROMEOS_EXPORT void SetMaxLogEntries(size_t max_entries);
  59
  60 // Adds an entry to the event log at level specified by |log_level|.
  61 // A maximum number of events are recorded after which new events replace
  62 // old ones. Error events are prioritized such that error events will only be
  63 // deleted if more than least half of the entries are errors (at which point
  64 // the oldest error entry will be replaced). Does nothing unless Initialize()
  65 // has been called. NOTE: Generally use NET_LOG instead.
  66 CHROMEOS_EXPORT void AddEntry(const char* file,
  67                               int file_line,
  68                               LogLevel log_level,
  69                               const std::string& event,
  70                               const std::string& description);
  71
  72 }  // namespace internal
  73
  74 // Outputs the log to a formatted string.
  75 // |order| determines which order to output the events.
  76 // |format| is a string that determines which elements to show. Elements
  77 // must be comma-separated, e.g. "time,desc".
  78 // Note: order of the format strings does not affect the output.
  79 //  "time" - Include a timestamp.
  80 //  "file" - Include file and line number.
  81 //  "desc" - Include the description.
  82 //  "html" - Include html tags.
  83 //  "json" - Return as JSON format
  84 // Only events with |log_level| <= |max_level| are included in the output.
  85 // If |max_events| > 0, limits how many events are output.
  86 // If |json| is specified, returns a JSON list of dictionaries containing time,
  87 // level, file, event, and description.
  88 CHROMEOS_EXPORT std::string GetAsString(StringOrder order,
  89                                         const std::string& format,
  90                                         LogLevel max_level,
  91                                         size_t max_events);
  92
  93 // Helper function for displaying a value as a string.
  94 CHROMEOS_EXPORT std::string ValueAsString(const base::Value& value);
  95
  96 // Errors
  97 #define NET_LOG_ERROR(event, desc) NET_LOG_LEVEL(                       \
  98     ::chromeos::network_event_log::LOG_LEVEL_ERROR, event, desc)
  99
 100 // Chrome initiated events, e.g. connection requests, scan requests,
 101 // configuration removal (either from the UI or from ONC policy application).
 102 #define NET_LOG_USER(event, desc) NET_LOG_LEVEL(                        \
 103     ::chromeos::network_event_log::LOG_LEVEL_USER, event, desc)
 104
 105 // Important events, e.g. state updates
 106 #define NET_LOG_EVENT(event, desc) NET_LOG_LEVEL(                       \
 107     ::chromeos::network_event_log::LOG_LEVEL_EVENT, event, desc)
 108
 109 // Non-essential debugging events
 110 #define NET_LOG_DEBUG(event, desc) NET_LOG_LEVEL(                       \
 111     ::chromeos::network_event_log::LOG_LEVEL_DEBUG, event, desc)
 112
 113 // Macro to include file and line number info in the event log.
 114 #define NET_LOG_LEVEL(log_level, event, description)            \
 115   ::chromeos::network_event_log::internal::AddEntry(            \
 116       __FILE__, __LINE__, log_level, event, description)
 117
 118 }  // namespace network_event_log
 119
 120 }  // namespace chromeos
 121
 122 #endif  // CHROMEOS_NETWORK_NETWORK_EVENT_LOG_H_