slog

package
v0.0.0-...-f7cdbce Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 29, 2024 License: MIT Imports: 8 Imported by: 1

Documentation

Overview

Package slog implements a slog.Handler that sends logs to a Loki instance.

The slog handler can be created directly using NewHandler or a slog.Logger can be created using NewLogger. These functions take a client.Client and a slog.HandlerOptions as arguments. Note that the slog.HandlerOptions are used differently than in the slog package. See the documentation of Handler for more information.

An important distinction when logging is that this Handler treats any attributes or groups added to the logger itself as labels for the stream in Loki. Attributes or groups included in the Record are treated as structured metadata.

JoinedHandler

The JoinedHandler is a slog.Handler that wraps multiple other handlers and sends logs to all of them. This can be used to send logs both to Loki and to other handlers, although there is no dependency on the Loki client.

If you need something more complex, another library such as slog-multi may be a better fit.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewJoinedLogger

func NewJoinedLogger(handlers ...slog.Handler) *slog.Logger

NewJoinedLogger creates a new slog.Logger with the given JoinedHandler constructed with the given handlers. It is equivalent to

slog.New(NewJoinedHandler(handlers...))

func NewLogger

func NewLogger(client client.Client, options *slog.HandlerOptions) *slog.Logger

NewLogger creates a new slog.Logger with the Handler attached. It is equivalent to

slog.New(NewHandler(client, options))

Types

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler implements the slog.Handler interface and sends logs to a Loki instance. It is best used to create a slog.Logger.

Labels vs Metadata

An important distinction when logging is that this Handler treats any attributes or groups added to the logger itself as labels for the stream in Loki. Attributes or groups included in the Record are treated as structured metadata.

Options

The Handler uses slog.HandlerOptions with the AddSource and Level fields functioning identical to its documentation. It uses the ReplaceAttr field in a very similar way to the documentation, but the built-in fields attributes are different. Only level and source are supported as time and message are passed directly to loki without the ability to be replaced.

func NewHandler

func NewHandler(client client.Client, options *slog.HandlerOptions) *Handler

NewHandler creates a new Handler with the given client and options. See the documentation of Handler for more information on how the options are used.

func (*Handler) Enabled

func (handler *Handler) Enabled(_ context.Context, level slog.Level) bool

Enabled returns true if the Handler is enabled for the given level.

func (*Handler) Handle

func (handler *Handler) Handle(_ context.Context, record slog.Record) error

Handle converts the given Record to a format compatible with Loki and pushes it to the Loki instance via the provided client.

func (*Handler) WithAttrs

func (handler *Handler) WithAttrs(attrs []slog.Attr) slog.Handler

WithAttrs returns a new Handler with the given attributes appended to the existing ones. These appear as stream labels in Loki.

func (*Handler) WithGroup

func (handler *Handler) WithGroup(name string) slog.Handler

WithGroup returns a new Handler with the given group name appended to the existing ones. These appear in Loki as prefixes of stream labels, separated by an underscore (`_`).

type JoinedHandler

type JoinedHandler struct {
	// contains filtered or unexported fields
}

JoinedHandler is a slog.Handler that wraps multiple other handlers and sends logs to all of them. Optionally, it can send logs to all handlers concurrently. If concurrency is left disabled, the order that logs are sent to the handlers is guaranteed to be the same as the order they are added to the JoinedHandler.

func NewJoinedHandler

func NewJoinedHandler(handlers ...slog.Handler) *JoinedHandler

NewJoinedHandler creates a new JoinedHandler with the given handlers.

func (*JoinedHandler) Enabled

func (handler *JoinedHandler) Enabled(ctx context.Context, level slog.Level) bool

Enabled returns true if any of the handlers in the JoinedHandler are enabled for the given level. Since Enabled is meant to be run on every log, Enabled functions should be fast and therefore this method is not affected by the concurrency option. It is safe to use from multiple goroutines.

func (*JoinedHandler) Handle

func (handler *JoinedHandler) Handle(ctx context.Context, record slog.Record) error

Handle sends the given Record to all of the handlers in the JoinedHandler. For safety, it clones the Record before passing it on to all handlers. It is safe to use from multiple goroutines.

If concurrency is disabled, the sending of logs short-circuits after the first error is encountered. If concurrency is enabled, the sending of logs continues until all handlers have been sent, although an error will be returned if any handler returns an error.

func (*JoinedHandler) WithAttrs

func (handler *JoinedHandler) WithAttrs(attrs []slog.Attr) slog.Handler

WithAttrs returns a new JoinedHandler with the given attributes appended to the existing ones for all handlers. Since ownership of the attrs is passed to each handler, the slice of attrs is cloned for each handler. Attrs will still share any state they hold since it is a shallow copy. Be careful.

It is safe to use from multiple goroutines.

func (*JoinedHandler) WithConcurrency

func (handler *JoinedHandler) WithConcurrency(concurrent bool) *JoinedHandler

WithConcurrency allows setting whether the JoinedHandler should send logs to all handlers concurrently. By default, it is false. Note that if this option is set to true, the order that logs are sent to the handlers is not guaranteed.

func (*JoinedHandler) WithGroup

func (handler *JoinedHandler) WithGroup(name string) slog.Handler

WithGroup returns a new JoinedHandler with the given group name appended to the existing ones for all handlers. It is safe to use from multiple goroutines.

func (*JoinedHandler) WithHandlers

func (handler *JoinedHandler) WithHandlers(handlers ...slog.Handler) *JoinedHandler

WithHandlers allows adding more handlers to the JoinedHandler after it has been created. If concurrency is disabled, these handlers are guaranteed to be sent after all existing handlers and in the order they are added.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL