This document describes the design and use of logging through NetLog.
Adding information to the NetLog helps debugging. However, logging also requires careful review as it can impact performance, privacy, and security.
Please add a net/log/OWNERS reviewer when adding new NetLog parameters, or adding information to existing ones.
The high level objectives when adding net logging code are:
kDefault
are safe to upload and share publicly.kDefault
has a low performance impact.kDefault
are small enough to upload to bug reports.To avoid doing work when logging is off, logging code should generally be conditional on NetLog::IsCapturing()
. Note that when specifying parameters via a lambda, the lambda is already conditional on IsCapturing()
.
NetLog parameters are specified as a JSON serializable base::Value
. This has some subtle implications:
base::Value::Type::STRING
with non-UTF-8 data.base::Value::Type::BINARY
(the JSON serializer can't handle it)Instead:
NetLogStringValue()
.NetLogBinaryValue()
.base::Value::Type::STRING
Also consider the maximum size of any string parameters:
kEverything
capture mode.NetLog parameters are specified as a JSON serializable base::Value
which does not support 64-bit integers.
Be careful when using base::Value::SetIntKey()
as it will truncate 64-bit values to 32-bits.
Instead use NetLogNumberValue()
.
There is no backwards compatibility requirement for NetLog events and their parameters, so you are free to change their structure/value as needed.
That said, changing core events may have consequences for external consumers of NetLogs, which rely on the structure and parameters to events for pretty printing and log analysis.
The NetLog viewer for instance pretty prints certain parameters based on their names, and the event name that added them.