net_log.h revision 5e3f23d412006dc4db4e659864679f29341e113f
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 NET_BASE_NET_LOG_H_ 6#define NET_BASE_NET_LOG_H_ 7 8#include <string> 9 10#include "base/atomicops.h" 11#include "base/basictypes.h" 12#include "base/callback_forward.h" 13#include "base/compiler_specific.h" 14#include "base/observer_list.h" 15#include "base/strings/string16.h" 16#include "base/synchronization/lock.h" 17#include "base/time.h" 18#include "net/base/net_export.h" 19 20namespace base { 21class DictionaryValue; 22class Value; 23} 24 25namespace net { 26 27// NetLog is the destination for log messages generated by the network stack. 28// Each log message has a "source" field which identifies the specific entity 29// that generated the message (for example, which URLRequest or which 30// SocketStream). 31// 32// To avoid needing to pass in the "source ID" to the logging functions, NetLog 33// is usually accessed through a BoundNetLog, which will always pass in a 34// specific source ID. 35// 36// All NetLog methods must be thread-safe. 37// 38// For a broader introduction see the design document: 39// https://sites.google.com/a/chromium.org/dev/developers/design-documents/network-stack/netlog 40class NET_EXPORT NetLog { 41 public: 42 enum EventType { 43#define EVENT_TYPE(label) TYPE_ ## label, 44#include "net/base/net_log_event_type_list.h" 45#undef EVENT_TYPE 46 EVENT_COUNT 47 }; 48 49 // The 'phase' of an event trace (whether it marks the beginning or end 50 // of an event.). 51 enum EventPhase { 52 PHASE_NONE, 53 PHASE_BEGIN, 54 PHASE_END, 55 }; 56 57 // The "source" identifies the entity that generated the log message. 58 enum SourceType { 59#define SOURCE_TYPE(label) SOURCE_ ## label, 60#include "net/base/net_log_source_type_list.h" 61#undef SOURCE_TYPE 62 SOURCE_COUNT 63 }; 64 65 // Specifies the granularity of events that should be emitted to the log. 66 // 67 // Since the LogLevel may be read and set on any thread without locking, it 68 // may be possible for an Observer to receive an event or parameters that 69 // normally wouldn't be logged at the currently active log level. 70 enum LogLevel { 71 // Log everything possible, even if it is slow and memory expensive. 72 // Includes logging of transferred bytes. 73 LOG_ALL, 74 75 // Log all events, but do not include the actual transferred bytes as 76 // parameters for bytes sent/received events. 77 LOG_ALL_BUT_BYTES, 78 79 // Only log events which are cheap, and don't consume much memory. This is 80 // the default value for observers. 81 LOG_BASIC, 82 83 // Don't log any events. 84 LOG_NONE, 85 }; 86 87 // A callback function that return a Value representation of the parameters 88 // associated with an event. If called, it will be called synchonously, 89 // so it need not have owning references. May be called more than once, or 90 // not at all. May return NULL. 91 typedef base::Callback<base::Value*(LogLevel)> ParametersCallback; 92 93 // Identifies the entity that generated this log. The |id| field should 94 // uniquely identify the source, and is used by log observers to infer 95 // message groupings. Can use NetLog::NextID() to create unique IDs. 96 struct NET_EXPORT Source { 97 static const uint32 kInvalidId; 98 99 Source(); 100 Source(SourceType type, uint32 id); 101 bool IsValid() const; 102 103 // Adds the source to a DictionaryValue containing event parameters, 104 // using the name "source_dependency". 105 void AddToEventParameters(base::DictionaryValue* event_params) const; 106 107 // Returns a callback that returns a dictionary with a single entry 108 // named "source_dependecy" that describes |this|. 109 ParametersCallback ToEventParametersCallback() const; 110 111 // Attempts to extract a Source from a set of event parameters. Returns 112 // true and writes the result to |source| on success. Returns false and 113 // makes |source| an invalid source on failure. 114 // TODO(mmenke): Long term, we want to remove this. 115 static bool FromEventParameters(base::Value* event_params, Source* source); 116 117 SourceType type; 118 uint32 id; 119 }; 120 121 class NET_EXPORT Entry { 122 public: 123 Entry(EventType type, 124 Source source, 125 EventPhase phase, 126 base::TimeTicks time, 127 const ParametersCallback* parameters_callback, 128 LogLevel log_level); 129 ~Entry(); 130 131 EventType type() const { return type_; } 132 Source source() const { return source_; } 133 EventPhase phase() const { return phase_; } 134 135 // Serializes the specified event to a Value. The Value also includes the 136 // current time. Caller takes ownership of returned Value. Takes in a time 137 // to allow back-dating entries. 138 base::Value* ToValue() const; 139 140 // Returns the parameters as a Value. Returns NULL if there are no 141 // parameters. Caller takes ownership of returned Value. 142 base::Value* ParametersToValue() const; 143 144 private: 145 const EventType type_; 146 const Source source_; 147 const EventPhase phase_; 148 const base::TimeTicks time_; 149 const ParametersCallback* parameters_callback_; 150 151 // Log level when the event occurred. 152 const LogLevel log_level_; 153 154 // It is not safe to copy this class, since |parameters_callback_| may 155 // include pointers that become stale immediately after the event is added, 156 // even if the code were modified to keep its own copy of the callback. 157 DISALLOW_COPY_AND_ASSIGN(Entry); 158 }; 159 160 // An observer, that must ensure its own thread safety, for events 161 // being added to a NetLog. 162 class NET_EXPORT ThreadSafeObserver { 163 public: 164 // Constructs an observer that wants to see network events, with 165 // the specified minimum event granularity. A ThreadSafeObserver can only 166 // observe a single NetLog at a time. 167 // 168 // Observers will be called on the same thread an entry is added on, 169 // and are responsible for ensuring their own thread safety. 170 // 171 // Observers must stop watching a NetLog before either the Observer or the 172 // NetLog is destroyed. 173 ThreadSafeObserver(); 174 175 // Returns the minimum log level for events this observer wants to 176 // receive. Must not be called when not watching a NetLog. 177 LogLevel log_level() const; 178 179 // Returns the NetLog we are currently watching, if any. Returns NULL 180 // otherwise. 181 NetLog* net_log() const; 182 183 // This method will be called on the thread that the event occurs on. It 184 // is the responsibility of the observer to handle it in a thread safe 185 // manner. 186 // 187 // It is illegal for an Observer to call any NetLog or 188 // NetLog::Observer functions in response to a call to OnAddEntry. 189 virtual void OnAddEntry(const Entry& entry) = 0; 190 191 protected: 192 virtual ~ThreadSafeObserver(); 193 194 private: 195 friend class NetLog; 196 197 // Both of these values are only modified by the NetLog. 198 LogLevel log_level_; 199 NetLog* net_log_; 200 201 DISALLOW_COPY_AND_ASSIGN(ThreadSafeObserver); 202 }; 203 204 NetLog(); 205 virtual ~NetLog(); 206 207 // Emits a global event to the log stream, with its own unique source ID. 208 void AddGlobalEntry(EventType type); 209 void AddGlobalEntry(EventType type, 210 const NetLog::ParametersCallback& parameters_callback); 211 212 // Returns a unique ID which can be used as a source ID. All returned IDs 213 // will be unique and greater than 0. 214 uint32 NextID(); 215 216 // Returns the logging level for this NetLog. This is used to avoid computing 217 // and saving expensive log entries. 218 LogLevel GetLogLevel() const; 219 220 // Adds an observer and sets its log level. The observer must not be 221 // watching any NetLog, including this one, when this is called. 222 // 223 // Typical observers should specify LOG_BASIC. 224 // 225 // Observers that need to see the full granularity of events can specify 226 // LOG_ALL_BUT_BYTES. However, doing so will have performance consequences. 227 // 228 // NetLog implementations must call NetLog::OnAddObserver to update the 229 // observer's internal state. 230 void AddThreadSafeObserver(ThreadSafeObserver* observer, LogLevel log_level); 231 232 // Sets the log level of |observer| to |log_level|. |observer| must be 233 // watching |this|. NetLog implementations must call 234 // NetLog::OnSetObserverLogLevel to update the observer's internal state. 235 void SetObserverLogLevel(ThreadSafeObserver* observer, LogLevel log_level); 236 237 // Removes an observer. NetLog implementations must call 238 // NetLog::OnAddObserver to update the observer's internal state. 239 // 240 // For thread safety reasons, it is recommended that this not be called in 241 // an object's destructor. 242 void RemoveThreadSafeObserver(ThreadSafeObserver* observer); 243 244 // Converts a time to the string format that the NetLog uses to represent 245 // times. Strings are used since integers may overflow. 246 static std::string TickCountToString(const base::TimeTicks& time); 247 248 // Returns a C-String symbolic name for |event_type|. 249 static const char* EventTypeToString(EventType event_type); 250 251 // Returns a dictionary that maps event type symbolic names to their enum 252 // values. Caller takes ownership of the returned Value. 253 static base::Value* GetEventTypesAsValue(); 254 255 // Returns a C-String symbolic name for |source_type|. 256 static const char* SourceTypeToString(SourceType source_type); 257 258 // Returns a dictionary that maps source type symbolic names to their enum 259 // values. Caller takes ownership of the returned Value. 260 static base::Value* GetSourceTypesAsValue(); 261 262 // Returns a C-String symbolic name for |event_phase|. 263 static const char* EventPhaseToString(EventPhase event_phase); 264 265 // Returns true if |log_level| indicates the actual bytes transferred should 266 // be logged. This is only the case when |log_level| is LOG_ALL. 267 static bool IsLoggingBytes(LogLevel log_level); 268 269 // Returns true if |log_level| indicates that all events should be logged, 270 // including frequently occuring ones that may impact performances. 271 // This is the case when |log_level| is LOG_ALL or LOG_ALL_BUT_BYTES. 272 static bool IsLoggingAllEvents(LogLevel log_level); 273 274 // Creates a ParametersCallback that encapsulates a single integer. 275 // Warning: |name| must remain valid for the life of the callback. 276 // TODO(mmenke): Rename this to be consistent with Int64Callback. 277 static ParametersCallback IntegerCallback(const char* name, int value); 278 279 // Creates a ParametersCallback that encapsulates a single int64. The 280 // callback will return the value as a StringValue, since IntegerValues 281 // only support 32-bit values. 282 // Warning: |name| must remain valid for the life of the callback. 283 static ParametersCallback Int64Callback(const char* name, int64 value); 284 285 // Creates a ParametersCallback that encapsulates a single UTF8 string. Takes 286 // |value| as a pointer to avoid copying, and emphasize it must be valid for 287 // the life of the callback. |value| may not be NULL. 288 // Warning: |name| and |value| must remain valid for the life of the callback. 289 static ParametersCallback StringCallback(const char* name, 290 const std::string* value); 291 292 // Same as above, but takes in a UTF16 string. 293 static ParametersCallback StringCallback(const char* name, 294 const base::string16* value); 295 296 protected: 297 // Set the lowest allowed log level, regardless of any Observers. 298 void SetBaseLogLevel(LogLevel log_level); 299 300 private: 301 friend class BoundNetLog; 302 303 void AddEntry(EventType type, 304 const Source& source, 305 EventPhase phase, 306 const NetLog::ParametersCallback* parameters_callback); 307 308 // Called whenever an observer is added or removed, or has its log level 309 // changed. Must have acquired |lock_| prior to calling. 310 void UpdateLogLevel(); 311 312 // |lock_| protects access to |observers_|. 313 base::Lock lock_; 314 315 // Last assigned source ID. Incremented to get the next one. 316 base::subtle::Atomic32 last_id_; 317 318 // The lowest allowed log level, regardless of any Observers. 319 // Normally defaults to LOG_NONE, but can be changed with SetBaseLogLevel 320 LogLevel base_log_level_; 321 322 // The current log level. 323 base::subtle::Atomic32 effective_log_level_; 324 325 // |lock_| must be acquired whenever reading or writing to this. 326 ObserverList<ThreadSafeObserver, true> observers_; 327 328 DISALLOW_COPY_AND_ASSIGN(NetLog); 329}; 330 331// Helper that binds a Source to a NetLog, and exposes convenience methods to 332// output log messages without needing to pass in the source. 333class NET_EXPORT BoundNetLog { 334 public: 335 BoundNetLog() : net_log_(NULL) {} 336 337 // Add a log entry to the NetLog for the bound source. 338 void AddEntry(NetLog::EventType type, NetLog::EventPhase phase) const; 339 void AddEntry(NetLog::EventType type, 340 NetLog::EventPhase phase, 341 const NetLog::ParametersCallback& get_parameters) const; 342 343 // Convenience methods that call AddEntry with a fixed "capture phase" 344 // (begin, end, or none). 345 void BeginEvent(NetLog::EventType type) const; 346 void BeginEvent(NetLog::EventType type, 347 const NetLog::ParametersCallback& get_parameters) const; 348 349 void EndEvent(NetLog::EventType type) const; 350 void EndEvent(NetLog::EventType type, 351 const NetLog::ParametersCallback& get_parameters) const; 352 353 void AddEvent(NetLog::EventType type) const; 354 void AddEvent(NetLog::EventType type, 355 const NetLog::ParametersCallback& get_parameters) const; 356 357 // Just like AddEvent, except |net_error| is a net error code. A parameter 358 // called "net_error" with the indicated value will be recorded for the event. 359 // |net_error| must be negative, and not ERR_IO_PENDING, as it's not a true 360 // error. 361 void AddEventWithNetErrorCode(NetLog::EventType event_type, 362 int net_error) const; 363 364 // Just like EndEvent, except |net_error| is a net error code. If it's 365 // negative, a parameter called "net_error" with a value of |net_error| is 366 // associated with the event. Otherwise, the end event has no parameters. 367 // |net_error| must not be ERR_IO_PENDING, as it's not a true error. 368 void EndEventWithNetErrorCode(NetLog::EventType event_type, 369 int net_error) const; 370 371 // Logs a byte transfer event to the NetLog. Determines whether to log the 372 // received bytes or not based on the current logging level. 373 void AddByteTransferEvent(NetLog::EventType event_type, 374 int byte_count, const char* bytes) const; 375 376 NetLog::LogLevel GetLogLevel() const; 377 378 // Shortcut for NetLog::IsLoggingBytes(this->GetLogLevel()). 379 bool IsLoggingBytes() const; 380 381 // Shortcut for NetLog::IsLoggingAllEvents(this->GetLogLevel()). 382 bool IsLoggingAllEvents() const; 383 384 // Helper to create a BoundNetLog given a NetLog and a SourceType. Takes care 385 // of creating a unique source ID, and handles the case of NULL net_log. 386 static BoundNetLog Make(NetLog* net_log, NetLog::SourceType source_type); 387 388 const NetLog::Source& source() const { return source_; } 389 NetLog* net_log() const { return net_log_; } 390 391 private: 392 BoundNetLog(const NetLog::Source& source, NetLog* net_log) 393 : source_(source), net_log_(net_log) { 394 } 395 396 NetLog::Source source_; 397 NetLog* net_log_; 398}; 399 400} // namespace net 401 402#endif // NET_BASE_NET_LOG_H_ 403