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