README
¶
Logger
Usage
slog
logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
Level: slog.LevelInfo,
}))
log.SetDefault(logger)
logger.InfoContext(ctx, "user created",
"user_id", userID,
"service.name", "helloworld",
)
Global logger
Common global helpers are still available for gradual migration. The signatures
now mirror slog: the first argument is the message, followed by key/value pairs
or slog.Attr values.
log.Info("started")
log.Info("listening", "addr", addr)
log.Info("service started", "service.name", "helloworld", "service.version", "v1.0.0")
log.InfoContext(ctx, "user created", "user_id", userID)
Builder
log.NewHandler builds a default handler. log.NewLogger wraps an existing
handler with Forge decorators. Attach fixed service attrs with logger.With.
logger := log.NewLogger(
slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
Level: slog.LevelInfo,
}),
log.WithFilter(log.WithFilterKey("password")), // redact sensitive keys
).With(
slog.String("service.id", id),
slog.String("service.name", name),
slog.String("service.version", version),
)
log.SetDefault(logger)
Context attrs
Attach attributes to a context.Context and they will flow through any
ctx-aware log call automatically.
ctx = log.ContextWithAttrs(ctx, slog.String("request_id", id))
log.InfoContext(ctx, "handling request")
OpenTelemetry
import (
otel "github.com/sylphylabs/forge/contrib/otel/log"
"github.com/sylphylabs/forge/log"
)
logger := log.NewLogger(otel.NewHandler("helloworld"))
log.SetDefault(logger)
The github.com/sylphylabs/forge/contrib/otel/log handler bridges slog records to
OpenTelemetry Logs. Use the core log builder when you need Forge logger options:
import (
"log/slog"
otel "github.com/sylphylabs/forge/contrib/otel/log"
"github.com/sylphylabs/forge/log"
)
logger := log.NewLogger(
otel.NewHandler("helloworld"),
log.WithFilter(log.WithFilterKey("password")),
).With(slog.String("service.name", "helloworld"))
Documentation
¶
Overview ¶
Package log builds structured loggers on the standard library's log/slog.
Forge defines no logger interface of its own: components accept and return *log/slog.Logger. NewHandler builds a composed handler with the package's defaults — text or JSON encoding (WithFormat), a minimum level (WithLevel), context-attribute extraction, and key redaction (WithFilter, WithFilterKey) — and NewLogger wraps any handler, including one from another package, in the same decorators.
ContextWithAttrs attaches attributes to a context; every record logged with that context through a composed handler carries them, which is how per-request values such as trace IDs reach log output without threading a logger through every call. SetDefault installs a logger as both this package's and slog's process default; the package-level helpers (With, WithGroup, Handler, Enabled) mirror the slog API on that default.
The OpenTelemetry bridge lives in the separate contrib/otel/log module; see docs/agent/observability.md for wiring logs into traces.
Index ¶
- Constants
- func AttrsFromContext(ctx context.Context) []slog.Attr
- func ContextWithAttrs(ctx context.Context, attrs ...slog.Attr) context.Context
- func Debug(msg string, args ...any)
- func DebugContext(ctx context.Context, msg string, args ...any)
- func Default() *slog.Logger
- func Enabled(ctx context.Context, level Level) bool
- func Error(msg string, args ...any)
- func ErrorContext(ctx context.Context, msg string, args ...any)
- func Handler() slog.Handler
- func Info(msg string, args ...any)
- func InfoContext(ctx context.Context, msg string, args ...any)
- func Log(ctx context.Context, level Level, msg string, args ...any)
- func LogAttrs(ctx context.Context, level Level, msg string, attrs ...slog.Attr)
- func NewHandler(opts ...Option) slog.Handler
- func NewLogger(handler slog.Handler, opts ...Option) *slog.Logger
- func SetDefault(logger *slog.Logger)
- func Warn(msg string, args ...any)
- func WarnContext(ctx context.Context, msg string, args ...any)
- func With(args ...any) *slog.Logger
- func WithGroup(name string) *slog.Logger
- type Extractor
- type FilterOption
- type Format
- type Level
- type LevelVar
- type Leveler
- type Option
- func WithAddSource(b bool) Option
- func WithExtractor(extractors ...Extractor) Option
- func WithFilter(opts ...FilterOption) Option
- func WithFormat(f Format) Option
- func WithLevel(l Leveler) Option
- func WithReplaceAttr(fn func(groups []string, a slog.Attr) slog.Attr) Option
- func WithWriter(w io.Writer) Option
Constants ¶
const LevelKey = slog.LevelKey
LevelKey is logger level key.
Variables ¶
This section is empty.
Functions ¶
func AttrsFromContext ¶
AttrsFromContext returns the attrs previously attached with ContextWithAttrs. The returned slice must not be mutated by callers.
func ContextWithAttrs ¶
ContextWithAttrs returns a copy of ctx with the given attrs attached. Attrs already on the context are preserved; new attrs are appended.
Use NewLogger or NewHandler so these attrs are automatically added to every record handled with that context.
func Debug ¶
Debug logs at debug level. Signature mirrors slog.Logger.Debug.
func DebugContext ¶
DebugContext logs at debug level with the provided context.
func Enabled ¶
Enabled reports whether the default logger emits log records at the given context and level. It mirrors slog.Logger.Enabled on the default logger.
func Error ¶
Error logs at error level. Signature mirrors slog.Logger.Error.
func ErrorContext ¶
ErrorContext logs at error level with the provided context.
func Handler ¶
Handler returns the default logger's handler. It mirrors slog.Logger.Handler on the default logger.
func Info ¶
Info logs at info level. Signature mirrors slog.Logger.Info.
func InfoContext ¶
InfoContext logs at info level with the provided context.
func Log ¶
Log emits a record at the given level. It mirrors slog.Logger.Log on the default logger.
func LogAttrs ¶
LogAttrs emits a typed-attr record at the given level. It mirrors slog.Logger.LogAttrs on the default logger.
func NewHandler ¶
NewHandler builds a composed slog.Handler with forge defaults:
- text encoding to stderr at LevelInfo
- context attrs from ContextWithAttrs are merged in
Additional decorators are layered as configured.
func SetDefault ¶
SetDefault sets the default logger used by the package-level helpers and by slog.Default.
func Warn ¶
Warn logs at warn level. Signature mirrors slog.Logger.Warn.
func WarnContext ¶
WarnContext logs at warn level with the provided context.
func With ¶
With returns a logger that includes the given attributes in each output operation. It mirrors slog.Logger.With on the default logger.
Types ¶
type FilterOption ¶
type FilterOption func(*filterConfig)
FilterOption configures filtering in WithFilter.
func WithFilterFunc ¶
WithFilterFunc drops records for which fn returns true. fn is evaluated after key redaction.
func WithFilterKey ¶
func WithFilterKey(keys ...string) FilterOption
WithFilterKey redacts the values of attributes whose key matches any of the provided keys. Keys may be leaf names ("password") or dotted group paths ("user.password").
type Level ¶
Level is a logger level.
func ParseLevel ¶
ParseLevel parses a level string into a logger Level value. It accepts the forms slog's slog.Level.UnmarshalText accepts, such as "INFO" and "ERROR+2", in any case. It returns an error when s names no known level.
type Option ¶
type Option func(*handlerConfig)
Option configures NewHandler and the decorators applied by NewLogger.
func WithAddSource ¶
WithAddSource toggles inclusion of the source file/line.
func WithExtractor ¶
WithExtractor appends attrs extracted from each log call context.
func WithFilter ¶
func WithFilter(opts ...FilterOption) Option
WithFilter applies the provided filter options on top of the composed handler.
func WithFormat ¶
WithFormat selects between text and JSON encoding. Defaults to FormatText.
func WithReplaceAttr ¶
WithReplaceAttr installs a custom ReplaceAttr on the base handler.
Source Files