Documentation
¶
Overview ¶
Package log is gojira's small slog-compatible logging facade.
It is a thin wrapper around the standard library's log/slog package that fixes two project-wide decisions and nothing more:
Output format. gojira supports exactly two encodings: "text" (human-readable key=value lines, suitable for terminals) and "json" (one JSON object per line, suitable for log shippers). Both encodings are implemented by stdlib handlers (slog.NewTextHandler and slog.NewJSONHandler); this package simply selects between them via the Format type.
Default handler options. Both handlers are constructed with AddSource=false. Adding file:line to every record is noisy for normal CLI use and is redundant for errors: gojira's error values are *errext.TraceError, which implement slog.LogValuer and emit a structured group containing the captured stack frames whenever they are logged.
The package is a public leaf: it imports only the Go standard library. It does not import any project-internal package and does not import any third-party logging library. Callers that need a *slog.Logger can use New; callers that want to compose handlers themselves (for example to add their own slog.Handler middleware) can use NewTextHandler or NewJSONHandler directly.
Goroutine safety: the handlers returned here are stdlib slog handlers, which are safe for concurrent use by multiple goroutines.
Index ¶
Constants ¶
const LevelTrace slog.Level = slog.LevelDebug - 4 // -8
LevelTrace is gojira's most verbose level, sitting below slog.LevelDebug. slog has no native Trace; this follows the conventional four-below-debug offset used by slog extensions that add a trace tier.
Variables ¶
This section is empty.
Functions ¶
func New ¶
New constructs a *slog.Logger that emits in the chosen format at or above the given level to w. It is the most convenient entry point for callers that do not need direct handler access.
An unknown Format value falls back to FormatText so a misconfigured caller still produces readable output rather than panicking.
func NewJSONHandler ¶
NewJSONHandler returns a slog.Handler that emits one JSON object per line at or above the given level. The returned handler is goroutine-safe.
func NewTextHandler ¶
NewTextHandler returns a slog.Handler that emits human-readable key=value lines at or above the given level. The returned handler is goroutine-safe.
func ParseLevel ¶
ParseLevel maps a case-insensitive level name to its slog.Level. Accepted: "error", "warn", "info", "debug", "trace". Leading and trailing whitespace is tolerated.
Use this instead of slog.Level.UnmarshalText when reading gojira configuration: UnmarshalText only knows the four built-in levels and would reject "trace".
The empty string is rejected (callers should validate non-empty upstream — gojira's config layer defaults LogLevel to "info" before it ever reaches here, so an empty value at this point indicates a bug worth surfacing).
Types ¶
type Format ¶
type Format int
Format selects the output encoding used by the handlers returned by New, NewTextHandler, and NewJSONHandler.
const ( // FormatText emits human-readable key=value lines via // slog.NewTextHandler. It is the default format and is suitable // for interactive terminal use. FormatText Format = iota // FormatJSON emits one JSON object per line via // slog.NewJSONHandler. It is suitable for log shippers and any // downstream consumer that parses structured logs. FormatJSON )
func ParseFormat ¶
ParseFormat accepts the case-insensitive strings "text" and "json" and returns the corresponding Format. Leading and trailing whitespace is not trimmed: callers are expected to normalise their input.
The empty string returns FormatText (the default) without an error so callers can pass an unset configuration value straight through without needing to check for emptiness first.
Any other input returns a non-nil error and the zero-value Format.
Source Files