net_log.h revision 5e3f23d412006dc4db4e659864679f29341e113f
15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Copyright (c) 2012 The Chromium Authors. All rights reserved. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Use of this source code is governed by a BSD-style license that can be 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// found in the LICENSE file. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef NET_BASE_NET_LOG_H_ 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define NET_BASE_NET_LOG_H_ 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <string> 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/atomicops.h" 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/basictypes.h" 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/callback_forward.h" 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/compiler_specific.h" 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/observer_list.h" 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/strings/string16.h" 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/synchronization/lock.h" 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/time.h" 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "net/base/net_export.h" 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace base { 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class DictionaryValue; 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class Value; 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace net { 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// NetLog is the destination for log messages generated by the network stack. 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Each log message has a "source" field which identifies the specific entity 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// that generated the message (for example, which URLRequest or which 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// SocketStream). 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// To avoid needing to pass in the "source ID" to the logging functions, NetLog 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// is usually accessed through a BoundNetLog, which will always pass in a 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// specific source ID. 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// All NetLog methods must be thread-safe. 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// For a broader introduction see the design document: 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// https://sites.google.com/a/chromium.org/dev/developers/design-documents/network-stack/netlog 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class NET_EXPORT NetLog { 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) enum EventType { 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define EVENT_TYPE(label) TYPE_ ## label, 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "net/base/net_log_event_type_list.h" 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#undef EVENT_TYPE 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) EVENT_COUNT 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) }; 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The 'phase' of an event trace (whether it marks the beginning or end 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // of an event.). 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) enum EventPhase { 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PHASE_NONE, 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PHASE_BEGIN, 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PHASE_END, 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) }; 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The "source" identifies the entity that generated the log message. 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) enum SourceType { 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define SOURCE_TYPE(label) SOURCE_ ## label, 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "net/base/net_log_source_type_list.h" 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#undef SOURCE_TYPE 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) SOURCE_COUNT 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) }; 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Specifies the granularity of events that should be emitted to the log. 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Since the LogLevel may be read and set on any thread without locking, it 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // may be possible for an Observer to receive an event or parameters that 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // normally wouldn't be logged at the currently active log level. 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) enum LogLevel { 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Log everything possible, even if it is slow and memory expensive. 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Includes logging of transferred bytes. 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) LOG_ALL, 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Log all events, but do not include the actual transferred bytes as 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // parameters for bytes sent/received events. 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) LOG_ALL_BUT_BYTES, 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Only log events which are cheap, and don't consume much memory. This is 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the default value for observers. 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) LOG_BASIC, 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Don't log any events. 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) LOG_NONE, 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) }; 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // A callback function that return a Value representation of the parameters 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // associated with an event. If called, it will be called synchonously, 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // so it need not have owning references. May be called more than once, or 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // not at all. May return NULL. 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) typedef base::Callback<base::Value*(LogLevel)> ParametersCallback; 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Identifies the entity that generated this log. The |id| field should 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // uniquely identify the source, and is used by log observers to infer 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // message groupings. Can use NetLog::NextID() to create unique IDs. 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) struct NET_EXPORT Source { 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static const uint32 kInvalidId; 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Source(); 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Source(SourceType type, uint32 id); 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool IsValid() const; 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Adds the source to a DictionaryValue containing event parameters, 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // using the name "source_dependency". 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void AddToEventParameters(base::DictionaryValue* event_params) const; 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns a callback that returns a dictionary with a single entry 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // named "source_dependecy" that describes |this|. 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ParametersCallback ToEventParametersCallback() const; 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Attempts to extract a Source from a set of event parameters. Returns 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // true and writes the result to |source| on success. Returns false and 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // makes |source| an invalid source on failure. 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // TODO(mmenke): Long term, we want to remove this. 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static bool FromEventParameters(base::Value* event_params, Source* source); 1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) SourceType type; 1185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) uint32 id; 1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) }; 1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) class NET_EXPORT Entry { 1225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Entry(EventType type, 1245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Source source, 1255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) EventPhase phase, 1265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) base::TimeTicks time, 1275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const ParametersCallback* parameters_callback, 1285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) LogLevel log_level); 1295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ~Entry(); 1305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) EventType type() const { return type_; } 1325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Source source() const { return source_; } 1335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) EventPhase phase() const { return phase_; } 1345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Serializes the specified event to a Value. The Value also includes the 1365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // current time. Caller takes ownership of returned Value. Takes in a time 1375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // to allow back-dating entries. 1385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) base::Value* ToValue() const; 1395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns the parameters as a Value. Returns NULL if there are no 1415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // parameters. Caller takes ownership of returned Value. 1425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) base::Value* ParametersToValue() const; 1435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) private: 1455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const EventType type_; 1465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const Source source_; 1475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const EventPhase phase_; 1485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const base::TimeTicks time_; 1495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const ParametersCallback* parameters_callback_; 1505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Log level when the event occurred. 1525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const LogLevel log_level_; 1535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // It is not safe to copy this class, since |parameters_callback_| may 1555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // include pointers that become stale immediately after the event is added, 1565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // even if the code were modified to keep its own copy of the callback. 1575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) DISALLOW_COPY_AND_ASSIGN(Entry); 1585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) }; 1595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // An observer, that must ensure its own thread safety, for events 1615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // being added to a NetLog. 1625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) class NET_EXPORT ThreadSafeObserver { 1635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 1645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Constructs an observer that wants to see network events, with 1655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the specified minimum event granularity. A ThreadSafeObserver can only 1665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // observe a single NetLog at a time. 1675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 1685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Observers will be called on the same thread an entry is added on, 1695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // and are responsible for ensuring their own thread safety. 1705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 1715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Observers must stop watching a NetLog before either the Observer or the 1725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // NetLog is destroyed. 1735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ThreadSafeObserver(); 1745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns the minimum log level for events this observer wants to 1765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 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