Documentation
¶
Overview ¶
Package logx is the mechanism behind the log contract (docs/logging.md): the request id carried in a context, the handler that stamps it on every line written under that context, and the sanitiser that keeps tokens and secrets out of a line and keeps a line below the size at which Docker splits it.
The vocabulary — the `event` names a line may carry — lives in internal/logevent; this package knows nothing about what is logged, only how.
Index ¶
- Constants
- func MaskEmail(addr string) string
- func MaskTokens(s string) string
- func New(o Options) *slog.Logger
- func ParseLevel(level string) slog.Level
- func RequestIDFrom(ctx context.Context) string
- func Sanitize(_ []string, a slog.Attr) slog.Attr
- func WithRequestID(ctx context.Context, id string) context.Context
- type Handler
- type Options
Constants ¶
const MaxStackLen = 8192
MaxStackLen is the bound for a `stack` attribute: a panic's stack is the one value worth most of the line, and 8 KB beside a 4 KB panic value and the line's other fields still stays under Docker's split.
const MaxStringLen = 4096
MaxStringLen bounds any string attribute. Docker splits a log line above 16 KB into 16,384-byte pieces that are no longer JSON and that nothing downstream can reassemble (measured); a line whose largest value is 4 KB stays well under that with room for the rest of its fields.
const Redacted = "[redacted]"
Redacted replaces a value under a secret-named key.
const RequestIDKey = "request_id"
RequestIDKey is the attribute every line written under a request carries.
Variables ¶
This section is empty.
Functions ¶
func MaskEmail ¶
MaskEmail keeps the first character of the local part and the domain: enough to tell which mailbox a line is about, not enough to be an address of a person (docs/logging.md: none in a line the contract adds).
func MaskTokens ¶
MaskTokens replaces every token-shaped substring with its display prefix and a marker. The server uses it to refuse an inbound value that a log line would carry masked; tests use it for things that must never log one.
func New ¶
New builds the contract's logger: JSON, one line per record, every attribute sanitised, the request id from the context on every line, the service identity on every line.
func ParseLevel ¶
ParseLevel maps the config's level names onto slog's; anything unknown is info, which is what the config's default means.
func RequestIDFrom ¶
RequestIDFrom returns the request id carried by ctx, or "".
func Sanitize ¶
Sanitize is the ReplaceAttr of the contract's handler: a value under a secret-named key is replaced, every string is masked of token-shaped substrings and cut at MaxStringLen, and both rules recurse into groups, maps, slices and errors. Masked, never dropped: a line about an incident is worth more than the value it would have leaked.
Types ¶
type Handler ¶
Handler stamps the context's request id on every record it handles. It wraps any slog.Handler; the wrapped handler's ReplaceAttr still sees the stamped attribute, so a request id is sanitised like everything else.
type Options ¶
type Options struct {
// Level is the minimum level: debug, info (the default), warn, error.
Level string
// Service, Role and Version are stamped on every line:
// the binary's name, the role it runs, the build.
Service, Role, Version string
// W is where lines go; nil means os.Stderr.
W io.Writer
}
Options configure New.