Documentation
¶
Overview ¶
Package logging provides centralized structured logging using slog with configurable log levels. Call InitLogger() from main() to configure.
Dynamic debug logging: Send SIGUSR1 to toggle debug mode at runtime (auto-reverts after 30 minutes). Example: docker kill -s SIGUSR1 <container>
Package logging provides centralized structured logging with optional remote log shipping.
Index ¶
- Constants
- func InitLogger(level string)
- func InitLoggerWithShipper(level string, shipperCfg ShipperConfig)
- func SetupTestLogger() func()
- func Shutdown()
- func ToggleDebug()
- type AsyncHandler
- func (h *AsyncHandler) Enabled(ctx context.Context, level slog.Level) bool
- func (h *AsyncHandler) Handle(ctx context.Context, r slog.Record) error
- func (h *AsyncHandler) Shutdown()
- func (h *AsyncHandler) WithAttrs(attrs []slog.Attr) slog.Handler
- func (h *AsyncHandler) WithGroup(name string) slog.Handler
- type LogEntry
- type Shipper
- type ShipperConfig
- type VictoriaShipper
Examples ¶
Constants ¶
const ( DefaultBatchSize = 100 DefaultFlushInterval = 5 * time.Second )
Default configuration values
Variables ¶
This section is empty.
Functions ¶
func InitLogger ¶
func InitLogger(level string)
InitLogger initializes the global slog default logger with the specified log level. Valid levels: debug, info, warn, error (case-insensitive) If level is empty or invalid, defaults to INFO. Call this from main() at startup.
Also starts a signal handler for SIGUSR1 to toggle debug mode at runtime.
func InitLoggerWithShipper ¶
func InitLoggerWithShipper(level string, shipperCfg ShipperConfig)
InitLoggerWithShipper initializes the global slog default logger with the specified log level and optional remote log shipping. Valid levels: debug, info, warn, error (case-insensitive) If level is empty or invalid, defaults to INFO. Call this from main() at startup.
If shipperCfg.Backend is non-empty, logs will be shipped to the configured remote service in addition to stdout.
Also starts a signal handler for SIGUSR1 to toggle debug mode at runtime.
func SetupTestLogger ¶
func SetupTestLogger() func()
SetupTestLogger configures logging for tests to reduce noise. Sets log level to WARN and outputs to io.Discard to suppress DEBUG and INFO messages. Returns a cleanup function that should be called when the test completes (use t.Cleanup).
Example ¶
Example test showing how to use SetupTestLogger
// In a test function:
cleanup := SetupTestLogger()
defer cleanup()
// Now logs at DEBUG and INFO are suppressed
slog.Debug("This won't show")
slog.Info("This won't show either")
slog.Warn("This WILL show")
// cleanup() will restore the original logger when defer runs
func Shutdown ¶
func Shutdown()
Shutdown flushes any remaining logs and closes the log shipper. Call this during graceful shutdown to ensure all logs are delivered.
func ToggleDebug ¶
func ToggleDebug()
ToggleDebug toggles between the original log level and DEBUG. When enabling debug, starts a 30-minute timer that auto-reverts. Typically called via SIGUSR1 signal.
Types ¶
type AsyncHandler ¶
type AsyncHandler struct {
// contains filtered or unexported fields
}
AsyncHandler is an slog.Handler that writes to stdout and optionally ships logs to a remote service asynchronously.
func NewAsyncHandler ¶
func NewAsyncHandler(stdout slog.Handler, shipper Shipper, cfg ShipperConfig, opts *slog.HandlerOptions) *AsyncHandler
NewAsyncHandler creates a new AsyncHandler that wraps stdout logging and optionally ships logs to a remote service.
func (*AsyncHandler) Enabled ¶
Enabled reports whether the handler handles records at the given level.
func (*AsyncHandler) Handle ¶
Handle handles the Record by writing to stdout and queuing for remote shipping.
func (*AsyncHandler) Shutdown ¶
func (h *AsyncHandler) Shutdown()
Shutdown flushes any remaining logs and closes the shipper. Call this during graceful shutdown.
type LogEntry ¶
type LogEntry struct {
Time time.Time
Level slog.Level
Message string
Source string
Attrs map[string]any
}
LogEntry represents a single log entry to be shipped.
type Shipper ¶
type Shipper interface {
// Ship sends a batch of log entries to the remote service.
// Returns an error if the batch could not be shipped.
Ship(ctx context.Context, entries []LogEntry) error
// Close cleanly shuts down the shipper, releasing any resources.
Close() error
}
Shipper defines the interface for log shipping backends. Implementations should be safe for concurrent use.
func NewShipper ¶
func NewShipper(cfg ShipperConfig) (Shipper, error)
NewShipper creates a shipper for the configured backend. Returns nil if no backend is configured (remote shipping disabled).
type ShipperConfig ¶
type ShipperConfig struct {
// Backend selects the shipping backend: "victoria", "opensearch", "loki", etc.
// Empty string disables remote shipping (stdout only).
Backend string
// URL is the remote service endpoint URL.
URL string
// BatchSize is the number of logs to batch before flushing.
// Default: 100
BatchSize int
// FlushInterval is the maximum time between flushes.
// Default: 5s
FlushInterval time.Duration
// Service identifies the source service ("appview" or "hold").
// Added to all log entries.
Service string
// Username for basic auth (optional).
Username string
// Password for basic auth (optional).
Password string
}
ShipperConfig configures the log shipper.
type VictoriaShipper ¶
type VictoriaShipper struct {
// contains filtered or unexported fields
}
VictoriaShipper ships logs to Victoria Logs using the native JSON lines endpoint.
func NewVictoriaShipper ¶
func NewVictoriaShipper(cfg ShipperConfig) (*VictoriaShipper, error)
NewVictoriaShipper creates a new Victoria Logs shipper.
func (*VictoriaShipper) Close ¶
func (v *VictoriaShipper) Close() error
Close releases any resources held by the shipper.
Source Files