README
¶
Logging Style Guide
The goal of the style described here is to yield logs that are amenable to searching and aggregating. Structured logging is the best foundation for that. The log entries should be consistent and predictable to support search efficiency and high fidelity of search results. This style puts forward guidelines that promote this outcome.
Log messages
-
Messages should be fixed strings, never interpolate values into the messages. Use log entry fields for values.
-
Message strings should be consistent identification of what action/event was/is happening. Consistent messages makes searching the logs and aggregating correlated events easier.
-
Error messages should look like any other log messages. No need to say "x failed", the log level and error field are sufficient indication of failure.
Log entry fields
-
Adding fields to log entries is not free, but the fields are the discriminators that allow distinguishing similar log entries from each other. Insufficient field structure will makes it more difficult to find the entries you are looking for.
-
Create/Use field helpers for commonly used field value types (see logging.go). It promotes consistent formatting and allows changing it easily in one place.
Log entry field helpers
- Make the field creation do as little as possible, i.e. just capture the existing value/object. Postpone any transformation to log emission time by employing generic zap.Stringer, zap.Array, zap.Object fields (see logging.go). It avoids unnecessary transformation for entries that may not even be emitted in the end.
Logger management
-
Adorn the logger with fields and reuse the adorned logger rather than repeatedly creating fields with each log entry.
-
Prefer passing the adorned logger down the call chain using Context. It promotes consistent log entry structure, i.e. fields will exist consistently in related entries.
Documentation
¶
Overview ¶
logging implements custom logging field types for commonly logged values like host ID or wallet address.
implementation purposely does as little as possible at field creation time, and postpones any transformation to output time by relying on the generic zap types like zap.Stringer, zap.Array, zap.Object
Index ¶
- func ENode(key string, node *enode.Node) zap.Field
- func Filters(filters []*pb.ContentFilter) zapcore.Field
- func From(ctx context.Context) *zap.Logger
- func HexArray(key string, byteVal byteArr) zapcore.Field
- func HexBytes(key string, bytes []byte) zap.Field
- func HostID(key string, id peer.ID) zapcore.Field
- func MultiAddrs(key string, addrs ...multiaddr.Multiaddr) zapcore.Field
- func PagingInfo(pi *pb.PagingInfo) zapcore.Field
- func TCPAddr(key string, ip net.IP, port int) zap.Field
- func Time(key string, time int64) zapcore.Field
- func UDPAddr(key string, ip net.IP, port int) zap.Field
- func With(ctx context.Context, log *zap.Logger) context.Context
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Filters ¶
func Filters(filters []*pb.ContentFilter) zapcore.Field
Filters creates a field with an array of history query filters. The assumption is that log entries won't have more than one of these, so the field key/name is hardcoded to be "filters" to promote consistency.
func From ¶
From allows retrieving the Logger from a Context. Returns nil if Context does not have one.
func HexArray ¶
HexArray creates a field with an array of bytes that will be shown as a hexadecimal string in logs
func HexBytes ¶
HexBytes creates a field for a byte slice that should be emitted as hex encoded string.
func MultiAddrs ¶
MultiAddrs creates a field with an array of multiaddrs
func PagingInfo ¶
func PagingInfo(pi *pb.PagingInfo) zapcore.Field
PagingInfo creates a field with history query paging info.
Types ¶
This section is empty.
Source Files