Generalize network_event_log -> device_event_log

chromeos/device_event_log.h

+// Copyright (c) 2014 The Chromium Authors. All rights reserved.

[Ben Chan, 2014/12/02 21:42:53]

drop (c)

http://www.chromium.org/developers/coding-style#TOC-File-headers

[stevenjb, 2014/12/03 00:16:04]

Done.

+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef CHROMEOS_DEVICE_EVENT_LOG_H_
+#define CHROMEOS_DEVICE_EVENT_LOG_H_
+
+#include <cstring>
+#include <sstream>
+
+#include "base/basictypes.h"
+#include "chromeos/chromeos_export.h"
+
+namespace chromeos {
+
+// This macro can be used to log chromeos device related events.
+// The following values should be used for |level| in these macros:
+//  ERROR An unexpected event, or a low level failure. Use sparingly.
+//  USER  An event that was initiated directly by a user (or Chrome) action.
+//  EVENT A default event type.
+//  DEBUG Useful debugging details that may not always be interesting.
+// Examples:
+//  NET_LOG(EVENT) << "NetworkState Changed " << name << ": " << state;
+//  POWER_LOG(USER) << "Suspend requested";
+
+#define NET_LOG(level)                                       \
+  DEVICE_LOG(::chromeos::device_event_log::LOG_TYPE_NETWORK, \
+             ::chromeos::device_event_log::LOG_LEVEL_##level)
+#define POWER_LOG(level)                                   \
+  DEVICE_LOG(::chromeos::device_event_log::LOG_TYPE_POWER, \
+             ::chromeos::device_event_log::LOG_LEVEL_##level)
+
+#define DEVICE_LOG(type, level)                                   \

[Ben Chan, 2014/12/02 21:42:53]

nit: perhaps default DEVICE_LOG first

[stevenjb, 2014/12/03 00:16:03]

I put this last since usually one of the above will be used. I'll clarify that
with a comment.

+  ::chromeos::device_event_log::internal::DeviceEventLogInstance( \
+      __FILE__, __LINE__, type, level).stream()
+
+namespace device_event_log {
+
+// Used to specify the type of event.
+enum LogType {
+  LOG_TYPE_NETWORK,
+  LOG_TYPE_POWER,
+  LOG_TYPE_NON_NETWORK,  // Match all non NETWORK log types

[Ben Chan, 2014/12/02 21:42:53]

why is NETWORK log a special case?  do we expect to have NON_POWER in the
future?

[stevenjb, 2014/12/03 00:16:03]

I'll add a comment. Currently there is much more network logging than anything
else and I expect that to continue for a while. If that changes we can consider
different approach.

+  LOG_TYPE_ALL,          // Match all log types
+};
+
+// Used to specify the detail level for logging. In GetAsString, used to
+// specify the maximum detail level (i.e. EVENT will include USER and ERROR).
+enum LogLevel {
+  LOG_LEVEL_ERROR = 0,
+  LOG_LEVEL_USER = 1,
+  LOG_LEVEL_EVENT = 2,

[Daniel Erat, 2014/12/02 20:43:16]

please add comments describing how to use these levels. is USER for
user-triggered events while EVENT is for system-triggered ones?

[stevenjb, 2014/12/02 21:14:38]

I put comments above, I will refer to that here.

[Daniel Erat, 2014/12/02 21:20:39]

ah, thanks. i scanned a bit above but missed that comment.

+  LOG_LEVEL_DEBUG = 3
+};
+
+// Used to specify which order to output event entries in GetAsString.
+enum StringOrder { OLDEST_FIRST, NEWEST_FIRST };
+
+// Initializes / shuts down device event logging. Calling Initialize more than
+// once will reset the log. If |max_entries| = 0 the default value will be used.
+CHROMEOS_EXPORT void Initialize(size_t max_entries);
+CHROMEOS_EXPORT void Shutdown();
+
+// Returns true if device event logging has been initialized.
+CHROMEOS_EXPORT bool IsInitialized();
+
+// Adds an entry to the global instance if initialized. Also always logs the

[Ben Chan, 2014/12/02 21:42:53]

nit: perhaps describe what happens if the instance isn't initialized?

[stevenjb, 2014/12/03 00:16:04]

I thought I did. I will rephrase this.

+// event to LOG(ERROR) or |type| = ERROR or VLOG(1) otherwise.
+CHROMEOS_EXPORT void AddEntry(const char* file,
+                              int line,
+                              LogType type,
+                              LogLevel level,
+                              const std::string& event);
+
+// For backwards compatibility with network_event_log. Combines |event| and
+// |description| and calls AddEntry().

[Ben Chan, 2014/12/02 21:42:53]

will this function be deprecated after the migration is done? if so, perhaps add
a TODO?

[stevenjb, 2014/12/03 00:16:04]

Someday maybe? There are 352 instances of NET_LOG_EVENT, etc, I don't expect to
deprecate this any time soon.

+CHROMEOS_EXPORT void AddEntryWithDescription(const char* file,
+                                             int line,
+                                             LogType type,
+                                             LogLevel level,
+                                             const std::string& event,
+                                             const std::string& description);
+
+// Outputs the log to a formatted string.
+// |order| determines which order to output the events.
+// |format| is a string that determines which elements to show. Elements
+// must be comma-separated, e.g. "time,desc".
+// Note: order of the format strings does not affect the output.
+//  "time" - Include a timestamp.
+//  "file" - Include file and line number.
+//  "type" - Include the event type.
+//  "html" - Include html tags.
+//  "json" - Return as JSON format
+// Only events matching |log_type| are included in the output.
+// Only events with |log_level| <= |max_level| are included in the output.
+// If |max_events| > 0, limits how many events are output.
+// If |json| is specified, returns a JSON list of dictionaries containing time,
+// level, file, event, and description.
+CHROMEOS_EXPORT std::string GetAsString(StringOrder order,
+                                        const std::string& format,
+                                        LogType log_type,
+                                        LogLevel max_level,
+                                        size_t max_events);
+
+CHROMEOS_EXPORT extern const LogLevel kDefaultLogLevel;
+
+namespace internal {
+
+class CHROMEOS_EXPORT DeviceEventLogInstance {
+ public:
+  DeviceEventLogInstance(const char* file,
+                         int line,
+                         device_event_log::LogType type,
+                         device_event_log::LogLevel level);
+  ~DeviceEventLogInstance();
+
+  std::ostream& stream() { return stream_; }
+
+ private:
+  const char* file_;
+  const int line_;
+  device_event_log::LogType type_;
+  device_event_log::LogLevel level_;
+  std::ostringstream stream_;
+
+  DISALLOW_COPY_AND_ASSIGN(DeviceEventLogInstance);
+};
+
+}  // namespace internal
+
+}  // namespace device_event_log
+
+}  // namespace chromeos
+
+#endif  // CHROMEOS_DEVICE_EVENT_LOG_H_