The highest tagged major version is
Documentation
¶
Overview ¶
Package logging is the Logger seam every package in this module writes through, and the noop that stands in when a caller supplies none.
Four backends implement it — slog, zap, zerolog, and otelgrpc, the last of which also ships records to an OTLP collector — and which one a deployment gets is configuration rather than a code change. Constructors take a Logger as a WithX option and never require one: EnsureLogger resolves a nil Logger to a noop, so a service that names no logger is a service that logs nothing, not one that fails to build.
The interface is narrow on purpose ¶
There are four emit methods — one per level — and a set of With* methods that derive a logger carrying more context. Error takes what was being attempted alongside the error, because "what failed" without "what was being tried" is the message that turns up in a search and answers nothing. Warn, like Info and Debug, takes only a message: a warning that has an error to report is an Error, and one that does not is a message. There are no formatting variants: a message is a constant and the variable parts are values, which is what makes a log line groupable after the fact.
Adding a method that takes a domain type is the mistake the interface exists to prevent — everything logs, so everything imports this package, and a method naming a type from elsewhere in the module makes that an import cycle.
What With* returns, and what that costs ¶
Every With* method and WithName return a logging.Logger, because that is what the interface says. A backend's own methods are therefore reachable on the value its constructor returned and not on anything derived from it: zap's SetLevel is the one that bites, since the derived loggers share the same atomic level and re-leveling still works — but only through the *zap.Logger the constructor handed back. Hold on to that value if a deployment intends to re-level at runtime.
Level is a string-backed type, so a level decoded from an environment variable equals the constant it names. The zero value is not a valid level; every backend reads it as InfoLevel.
Every level names both a threshold and a method, WarnLevel included: configuring WarnLevel drops Info and Debug and keeps Warn and Error, and each backend maps it onto that backend's own warn level rather than onto info or error.
Index ¶
Constants ¶
const (
// LoggerNameKey is a key we can use to denote logger names across implementations.
LoggerNameKey = "service_name"
)
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Level ¶
type Level string
Level names the severity threshold a Logger emits at.
It is a string-backed value type, so == compares the level rather than a pointer, and a Level decoded from env or JSON equals the constant it names. The zero value is the empty Level, which every implementation reads as InfoLevel.
type Logger ¶
type Logger interface {
Info(string)
Debug(string)
Warn(string)
Error(whatWasHappeningWhenErrorOccurred string, err error)
SetRequestIDFunc(RequestIDFunc)
Clone() Logger
WithName(string) Logger
WithValues(map[string]any) Logger
WithValue(string, any) Logger
WithRequest(*http.Request) Logger
WithResponse(response *http.Response) Logger
WithError(error) Logger
WithSpan(span trace.Span) Logger
}
Logger represents a simple logging interface we can build wrappers around. NOTICE: someone, naive and green, may be enticed to add a method to this interface akin to: WithQueryFilter(*types.QueryFilter) Logger This is a fool's errand, it would introduce a disallowed import cycle.
func EnsureLogger ¶
EnsureLogger guarantees that a Logger is available.
func NewNamedLogger ¶
NewNamedLogger creates a named Logger from the given Logger. If logger is nil, a noop Logger is used.
type RequestIDFunc ¶
RequestIDFunc fetches a string ID from a request.
type RequestInfo ¶
RequestInfo holds HTTP request metadata extracted for logging.
func ExtractRequestInfo ¶
func ExtractRequestInfo(req *http.Request, requestIDFunc RequestIDFunc) RequestInfo
ExtractRequestInfo extracts logging-relevant fields from an HTTP request.
type SpanInfo ¶
SpanInfo holds span and trace IDs extracted from a trace.Span.
func ExtractSpanInfo ¶
ExtractSpanInfo extracts span and trace IDs from a trace.Span. A nil span yields a zero-value SpanInfo rather than panicking, so WithSpan(nil) is safe.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package loggingcfg selects and builds a logging.Logger from configuration: zerolog, zap, slog, the OTel-exporting slog, or none at all.
|
Package loggingcfg selects and builds a logging.Logger from configuration: zerolog, zap, slog, the OTel-exporting slog, or none at all. |
|
Package noop is the logging.Logger that writes nowhere.
|
Package noop is the logging.Logger that writes nowhere. |
|
Package otelgrpc implements logging.Logger over log/slog, fanning every record out to both stdout and an OTLP collector reached over gRPC.
|
Package otelgrpc implements logging.Logger over log/slog, fanning every record out to both stdout and an OTLP collector reached over gRPC. |
|
Package slog implements logging.Logger over the standard library's log/slog, emitting JSON to stdout.
|
Package slog implements logging.Logger over the standard library's log/slog, emitting JSON to stdout. |
|
Package zap implements logging.Logger over uber-go/zap.
|
Package zap implements logging.Logger over uber-go/zap. |
|
Package zerolog implements logging.Logger over rs/zerolog.
|
Package zerolog implements logging.Logger over rs/zerolog. |