Documentation
¶
Overview ¶
Package logging provides a pre-configured log/slog.Logger factory with consistent defaults for the ToolHive ecosystem.
All ToolHive projects share the same timestamp format, output destination, and handler configuration. This package encapsulates those choices so that each project does not need to replicate them.
Defaults ¶
- Format: JSON (FormatJSON) via log/slog.JSONHandler
- Level: INFO (log/slog.LevelInfo)
- Output: os.Stderr
- Timestamps: time.RFC3339
Basic Usage ¶
Create a logger with default settings:
logger := logging.New()
logger.Info("server started", "port", 8080)
Configuration ¶
Use functional options to customize the logger:
logger := logging.New( logging.WithFormat(logging.FormatText), logging.WithLevel(slog.LevelDebug), )
Dynamic Level Changes ¶
Pass a log/slog.LevelVar to change the level at runtime:
var lvl slog.LevelVar logger := logging.New(logging.WithLevel(&lvl)) lvl.Set(slog.LevelDebug) // takes effect immediately
Testing ¶
Inject a buffer to capture log output in tests:
var buf bytes.Buffer
logger := logging.New(logging.WithOutput(&buf))
logger.Info("test message")
// inspect buf.String()
Handler Access ¶
Use NewHandler when you need to wrap the handler with middleware:
base := logging.NewHandler(logging.WithLevel(slog.LevelDebug))
wrapped := &myMiddleware{Handler: base}
logger := slog.New(wrapped)
Stability ¶
This package is Alpha stability. The API may change without notice. See the toolhive-core README for stability level definitions.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
New creates a pre-configured *log/slog.Logger with consistent defaults used across the ToolHive ecosystem.
Defaults:
- Format: JSON (FormatJSON)
- Level: INFO (log/slog.LevelInfo)
- Output: os.Stderr
- Timestamps: time.RFC3339
func NewHandler ¶ added in v0.0.5
NewHandler creates a pre-configured log/slog.Handler with consistent defaults used across the ToolHive ecosystem. Use WithHandlerMiddleware to wrap the handler with cross-cutting concerns (e.g., trace injection) before the final logger is created — or, for a one-off need, call NewHandler and wrap its return value directly instead of creating the final logger with New.
Defaults:
- Format: JSON (FormatJSON)
- Level: INFO (log/slog.LevelInfo)
- Output: os.Stderr
- Timestamps: time.RFC3339
func ParseLevel ¶ added in v0.0.33
ParseLevel parses a level name ("debug", "info", "warn", or "error") into a log/slog.Level. An empty string resolves to log/slog.LevelInfo, matching New's default.
Types ¶
type Format ¶
type Format int
Format represents the log output format.
const ( // FormatJSON produces JSON-formatted log output using [log/slog.JSONHandler]. // This is the default format, suitable for production environments. FormatJSON Format = iota // FormatText produces human-readable text output using [log/slog.TextHandler]. // This is suitable for local development. FormatText )
type Option ¶
type Option func(*config)
Option configures New and NewHandler.
func WithFormat ¶
WithFormat sets the output format (JSON or Text). The default is FormatJSON.
func WithHandlerMiddleware ¶ added in v0.0.51
WithHandlerMiddleware wraps the handler NewHandler builds with fn before returning it, so a caller can inject a cross-cutting concern — trace-context stamping, redaction, sampling, or anything else expressible as func(slog.Handler) slog.Handler — without this package taking a dependency on it. Applying more than one middleware is equivalent to manually chaining fn calls in the given order: the last WithHandlerMiddleware call wraps every earlier one, so it is the outermost handler and sees (and can filter or annotate) each record before the others do.
handler := logging.NewHandler( logging.WithFormat(logging.FormatText), logging.WithHandlerMiddleware(myTraceContextHandler), )
func WithLevel ¶
WithLevel sets the minimum log level. The default is log/slog.LevelInfo.
Accepts any log/slog.Leveler, including *log/slog.LevelVar for dynamic level changes:
var lvl slog.LevelVar lvl.Set(slog.LevelDebug) logger := logging.New(logging.WithLevel(&lvl))
Source Files