slog

Documentation

Overview

Package slog provides integration between Go's structured logging (slog) and audit logging. It allows audit events to be automatically created from slog log entries based on configurable extraction and filtering rules.

Index

• Constants
• func AttrExtractor(key string) func(attrs []slog.Attr) (string, bool)
• func DefaultActionExtractor(attrs []slog.Attr) audit.Action
• func DefaultAuthorExtractor(ctx context.Context, attrs []slog.Attr) string
• func DefaultPayloadExtractor(attrs []slog.Attr) map[string]audit.Value
• type Handler
  • func NewHandler(logger *audit.Logger, opts HandlerOptions) *Handler
  • func (h *Handler) Enabled(ctx context.Context, level slog.Level) bool
  • func (h *Handler) Handle(ctx context.Context, record slog.Record) error
  • func (h *Handler) WithAttrs(attrs []slog.Attr) slog.Handler
  • func (h *Handler) WithGroup(name string) slog.Handler
• type HandlerOptions

Constants

const (
	// AttrEntity is the key for the entity identifier (required for audit).
	// Example: slog.Info("...", slog.AttrEntity, "user:123").
	AttrEntity = "entity"

	// AttrAction is the key for the action type (create, update, delete).
	// Example: slog.Info("...", slog.AttrAction, "update").
	AttrAction = "action"

	// AttrAuthor is the key for the author/user who performed the action.
	// Example: slog.Info("...", slog.AttrAuthor, "admin").
	AttrAuthor = "author"

	// AttrUser is an alternative key for the author (use either AttrAuthor or AttrUser).
	// Example: slog.Info("...", slog.AttrUser, "john.doe").
	AttrUser = "user"
)

Attribute keys used for audit logging. Use these constants when logging to ensure correct extraction.

Functions

func AttrExtractor

func AttrExtractor(key string) func(attrs []slog.Attr) (string, bool)

AttrExtractor is a helper to extract a specific attribute by key.

func DefaultActionExtractor

func DefaultActionExtractor(attrs []slog.Attr) audit.Action

DefaultActionExtractor extracts action from AttrAction attribute. Defaults to ActionCreate if not found.

func DefaultAuthorExtractor

func DefaultAuthorExtractor(ctx context.Context, attrs []slog.Attr) string

DefaultAuthorExtractor extracts author from AttrAuthor or AttrUser attribute. Defaults to "system" if not found.

func DefaultPayloadExtractor

func DefaultPayloadExtractor(attrs []slog.Attr) map[string]audit.Value

DefaultPayloadExtractor includes all attributes except reserved keys. Reserved keys: AttrEntity, AttrAction, AttrAuthor, AttrUser.

Types

type Handler

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

Handler is a slog.Handler that writes audit logs based on slog records. It delegates to another handler for normal logging while optionally sending matching records to an audit logger.

func NewHandler

func NewHandler(logger *audit.Logger, opts HandlerOptions) *Handler

NewHandler creates a new slog.Handler that sends matching records to audit.

Example:

handler := slog.NewHandler(auditLogger, slog.HandlerOptions{
    Handler: slog.NewJSONHandler(os.Stdout, nil),
    KeyExtractor: func(attrs []slog.Attr) (string, bool) {
        for _, attr := range attrs {
            if attr.Key == "entity" {
                return attr.Value.String(), true
            }
        }
        return "", false
    },
    ShouldAudit: func(record slog.Record) bool {
        return record.Level >= slog.LevelInfo
    },
})

func (*Handler) Enabled

func (h *Handler) Enabled(ctx context.Context, level slog.Level) bool

Enabled reports whether the handler handles records at the given level. It delegates to the underlying handler if present.

func (*Handler) Handle

func (h *Handler) Handle(ctx context.Context, record slog.Record) error

Handle processes a slog.Record, optionally sending it to audit.

func (*Handler) WithAttrs

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

WithAttrs returns a new Handler with additional attributes.

func (*Handler) WithGroup

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

WithGroup returns a new Handler with a group name.

type HandlerOptions

type HandlerOptions struct {
	// Handler is the underlying slog.Handler to delegate to for normal logging.
	// If nil, logs will only go to audit (no regular logging).
	Handler slog.Handler

	// ShouldAudit determines whether a log record should be sent to audit.
	// If nil, all records are audited.
	ShouldAudit func(record slog.Record) bool

	// KeyExtractor extracts the entity key from log attributes.
	// Required. Must return (key, true) if found, ("", false) otherwise.
	KeyExtractor func(attrs []slog.Attr) (string, bool)

	// ActionExtractor extracts the action from log attributes.
	// If nil, uses ActionCreate by default.
	ActionExtractor func(attrs []slog.Attr) audit.Action

	// AuthorExtractor extracts the author from log attributes or context.
	// If nil, uses "system" as default.
	AuthorExtractor func(ctx context.Context, attrs []slog.Attr) string

	// PayloadExtractor extracts the payload from log attributes.
	// If nil, includes all attributes except those used for key/action/author.
	PayloadExtractor func(attrs []slog.Attr) map[string]audit.Value
}

HandlerOptions configures how slog records are converted to audit logs.