2026-01-28 13:37:22 +00:00
|
|
|
// Package zlog provides zerolog utilities for safe and consistent logging.
|
|
|
|
|
//
|
|
|
|
|
// This package contains:
|
all: apply godoc [Name] link conventions across comments
Every Go-identifier reference in // and /* */ comments now uses
godoc's [Name] linking syntax so pkg.go.dev and `go doc` render
them as clickable cross-references. No behaviour change.
Pattern applied across the tree:
In-package [Foo], [Foo.Bar]
Cross-package [pkg.Foo], [pkg.Foo.Bar]
Stdlib [netip.Prefix], [errors.Is], [context.Context]
Tailscale [tailcfg.MapResponse], [tailcfg.Node.CapMap],
[tailcfg.NodeAttrSuggestExitNode]
Skip rules:
- File:line refs left as plain text
- HuJSON wire keys inside backtick raw strings untouched
- ACL/policy syntax tokens (tag:foo, autogroup:self, ...) not Go
symbols, left as plain text
- JSON/OIDC wire keys, gorm tags, RFC IPv6 placeholders, markdown
link tags, decorative dividers — all left as-is
2026-05-18 18:35:53 +00:00
|
|
|
// - Safe wrapper types for external types ([tailcfg.Hostinfo], [tailcfg.MapRequest])
|
|
|
|
|
// that implement [zerolog.LogObjectMarshaler] with security-conscious field redaction
|
2026-01-28 13:37:22 +00:00
|
|
|
//
|
|
|
|
|
// For field name constants, use the zf subpackage:
|
|
|
|
|
//
|
|
|
|
|
// import "github.com/juanfont/headscale/hscontrol/util/zlog/zf"
|
|
|
|
|
//
|
|
|
|
|
// # Usage Pattern: Sub-Loggers
|
|
|
|
|
//
|
|
|
|
|
// The recommended pattern is to create sub-loggers at function entry points:
|
|
|
|
|
//
|
|
|
|
|
// func (m *mapSession) serve() {
|
|
|
|
|
// log := log.With().
|
|
|
|
|
// EmbedObject(m.node).
|
|
|
|
|
// EmbedObject(zlog.MapRequest(&m.req)).
|
|
|
|
|
// Logger()
|
|
|
|
|
//
|
|
|
|
|
// log.Info().Msg("Map session started")
|
|
|
|
|
// log.Debug().Caller().Msg("Processing request")
|
|
|
|
|
// }
|
|
|
|
|
//
|
|
|
|
|
// # Security Considerations
|
|
|
|
|
//
|
|
|
|
|
// The wrapper types in this package intentionally redact sensitive information:
|
|
|
|
|
// - Device fingerprinting data (OS version, device model, etc.)
|
|
|
|
|
// - Client endpoints and IP addresses
|
|
|
|
|
// - Full authentication keys (only prefixes are logged)
|
|
|
|
|
package zlog
|
