package alog

import "github.com/go-arrower/arrower/alog"

Package alog provides a logger that is a subset of the slog.Logger interface. The alog.Logger encourages to only use debug and info levels. More leves are not required, if all errors are handled properly in Go.

Additionally, alog provides a logger implementation different stages of the software, from development and testing to production.

package main

import (
	"context"
	"log/slog"
	"os"

	"go.opentelemetry.io/otel/trace"

	"github.com/go-arrower/arrower/alog"
)

func main() {
	// Manually create a custom TraceID and SpanID for the root span to ensure deterministic IDs for assertion.
	traceID := trace.TraceID([16]byte{0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef, 0xfe, 0xdc, 0xba, 0x98, 0x76, 0x54, 0x32, 0x10})
	spanID := trace.SpanID([8]byte{0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef})

	newCtx := trace.ContextWithSpanContext(
		context.Background(),
		trace.NewSpanContext(trace.SpanContextConfig{
			TraceID:    traceID,
			SpanID:     spanID,
			TraceFlags: trace.FlagsSampled,
		}),
	)

	logger := alog.New(alog.WithHandler(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
		ReplaceAttr: removeTime,
	})))

	logger.InfoContext(newCtx, "")
	logger.InfoContext(newCtx, "", slog.String("key", "val"))

	logger = logger.With("attr", "val")
	logger.InfoContext(newCtx, "", slog.String("key", "val"))

	contextA := logger.WithGroup("context_a")
	contextA.InfoContext(newCtx, "", slog.String("key", "val"))

	contextB := logger.WithGroup("context_b")
	contextB.InfoContext(newCtx, "", slog.String("key", "val"))

	contextBA := contextB.WithGroup("context_a")
	contextBA.InfoContext(newCtx, "", slog.String("key", "val"))

}

// removeTime to have deterministic output for assertion.
func removeTime(_ []string, attr slog.Attr) slog.Attr {
	if attr.Key == slog.TimeKey {
		attr = slog.Attr{}
	}

	return attr
}

level=INFO msg="" traceID=0123456789abcdeffedcba9876543210 spanID=0123456789abcdef
level=INFO msg="" key=val traceID=0123456789abcdeffedcba9876543210 spanID=0123456789abcdef
level=INFO msg="" attr=val key=val traceID=0123456789abcdeffedcba9876543210 spanID=0123456789abcdef
level=INFO msg="" attr=val context_a.key=val context_a.traceID=0123456789abcdeffedcba9876543210 context_a.spanID=0123456789abcdef
level=INFO msg="" attr=val context_b.key=val context_b.traceID=0123456789abcdeffedcba9876543210 context_b.spanID=0123456789abcdef
level=INFO msg="" attr=val context_b.context_a.key=val context_b.context_a.traceID=0123456789abcdeffedcba9876543210 context_b.context_a.spanID=0123456789abcdef

Index ¶

• Constants
• Variables
• func AddAttr(ctx context.Context, attr slog.Attr) context.Context
• func AddAttrs(ctx context.Context, newAttrs ...slog.Attr) context.Context
• func ClearAttrs(ctx context.Context) context.Context
• func FromContext(ctx context.Context) ([]slog.Attr, bool)
• func MapLogLevelsToName(_ []string, attr slog.Attr) slog.Attr
• func New(opts ...LoggerOpt) *slog.Logger
• func NewDevelopment(pgx *pgxpool.Pool) *slog.Logger
• func NewNoop() *slog.Logger
• type ArrowerLogger
• func Unwrap(logger Logger) ArrowerLogger
• type Logger
• type LoggerOpt
• func WithHandler(h slog.Handler) LoggerOpt
• func WithLevel(level slog.Level) LoggerOpt
• func WithSettings(settings setting.Settings) LoggerOpt
• type LokiHandler
• func NewLokiHandler(opt *LokiHandlerOptions) *LokiHandler
• func (l *LokiHandler) Enabled(_ context.Context, _ slog.Level) bool
• func (l *LokiHandler) Handle(ctx context.Context, record slog.Record) error
• func (l *LokiHandler) WithAttrs(attrs []slog.Attr) slog.Handler
• func (l *LokiHandler) WithGroup(name string) slog.Handler
• type LokiHandlerOptions
• type PostgresHandler
• func NewPostgresHandler(pgx *pgxpool.Pool, opt *PostgresHandlerOptions) *PostgresHandler
• func (l *PostgresHandler) Enabled(_ context.Context, _ slog.Level) bool
• func (l *PostgresHandler) Handle(ctx context.Context, record slog.Record) error
• func (l *PostgresHandler) WithAttrs(attrs []slog.Attr) slog.Handler
• func (l *PostgresHandler) WithGroup(name string) slog.Handler
• type PostgresHandlerOptions
• type TestLogger
• func Test(t *testing.T) *TestLogger
• func (l *TestLogger) Contains(contains string, msgAndArgs ...any) bool
• func (l *TestLogger) Empty(msgAndArgs ...any) bool
• func (l *TestLogger) Level() slog.Level
• func (l *TestLogger) Lines() []string
• func (l *TestLogger) NotContains(notContains string, msgAndArgs ...any) bool
• func (l *TestLogger) NotEmpty(msgAndArgs ...any) bool
• func (l *TestLogger) SetLevel(level slog.Level)
• func (l *TestLogger) String() string
• func (l *TestLogger) Total(total int, msgAndArgs ...any) bool
• func (l *TestLogger) UsesSettings() bool

Examples ¶

• package (LogOutputNestingWithTraces)

Constants ¶

const (
	// LevelInfo is used to see what is going on inside arrower.
	LevelInfo = slog.Level(-8)

	// LevelDebug is used by arrower developers, if you really want to know what is going on.
	LevelDebug = slog.Level(-12)
)

const CtxAttr ctx2.CTXKey = "arrower.slog"

CtxAttr contains request scoped attributes.

Variables ¶

var (
	SettingLogLevel = setting.NewKey("arrower", "log", "level") //nolint:gochecknoglobals
	SettingLogUsers = setting.NewKey("arrower", "log", "users") //nolint:gochecknoglobals
)

var ErrLogFailed = errors.New("could not save log")

Functions ¶

func AddAttr ¶

func AddAttr(ctx context.Context, attr slog.Attr) context.Context

AddAttr adds a single attribute to ctx. All attrs in CtxAttr will be logged automatically by the arrowerHandler.

func AddAttrs ¶

func AddAttrs(ctx context.Context, newAttrs ...slog.Attr) context.Context

AddAttrs adds multiple attributes to ctx. All attrs in CtxAttr will be logged automatically by the arrowerHandler.

func ClearAttrs ¶

func ClearAttrs(ctx context.Context) context.Context

ClearAttrs does remove all attributes from CtxAttr.

func FromContext ¶

func FromContext(ctx context.Context) ([]slog.Attr, bool)

FromContext returns the attributes stored in ctx, if any.

func MapLogLevelsToName ¶

func MapLogLevelsToName(_ []string, attr slog.Attr) slog.Attr

MapLogLevelsToName replaces the default name of a custom log level with an speaking name for the arrower levels.

func New ¶

func New(opts ...LoggerOpt) *slog.Logger

New returns a production ready logger.

If no options are given it creates a default handler, logging JSON to Stderr. Otherwise, use WithHandler to set your own loggers. For an example of options at work, see NewDevelopment.

func NewDevelopment ¶

func NewDevelopment(pgx *pgxpool.Pool) *slog.Logger

NewDevelopment returns a logger ready for local development purposes. If pgx is nil the returned logger is not initialised to use any of the database related features of alog.

func NewNoop ¶

func NewNoop() *slog.Logger

NewNoop returns an implementation of Logger that performs no operations. Ideal as dependency in tests.

Types ¶

type ArrowerLogger ¶

type ArrowerLogger interface {
	SetLevel(level slog.Level)
	Level() slog.Level
	UsesSettings() bool
}

ArrowerLogger is an extension to Logger and slog.Logger and offers additional control over the logger at run time. Unwrap a logger to get access to this features.

func Unwrap ¶

func Unwrap(logger Logger) ArrowerLogger

Unwrap unwraps the given logger and returns a ArrowerLogger. In case of an invalid implementation of logger, it returns nil.

type Logger ¶

type Logger interface {
	Log(ctx context.Context, level slog.Level, msg string, args ...any)
	LogAttrs(ctx context.Context, level slog.Level, msg string, attrs ...slog.Attr)
	DebugContext(ctx context.Context, msg string, args ...any)
	InfoContext(ctx context.Context, msg string, args ...any)

	With(args ...any) *slog.Logger
	WithGroup(name string) *slog.Logger
}

Logger interface is a subset of slog.Logger, with the aim to:

1. encourage the use of the methods offering context.Context, so that tracing information can be correlated, see: https://www.arrower.org/docs/basics/observability/logging#correlate-with-tracing
2. encourage the use of the levels `DEBUG` and `INFO` over others, but without preventing them, see: https://dave.cheney.net/2015/11/05/lets-talk-about-logging

type LoggerOpt ¶

type LoggerOpt func(logger *arrowerHandler)

LoggerOpt allows to initialise a logger with custom options.

func WithHandler ¶

func WithHandler(h slog.Handler) LoggerOpt

WithHandler adds a slog.Handler to be logged to. You can set as many as you want.

func WithLevel ¶

func WithLevel(level slog.Level) LoggerOpt

WithLevel initialises the logger with a starting level. To change the level at runtime use ArrowerLogger.SetLevel: Unwrap(logger).SetLevel(LevelInfo).

func WithSettings ¶

func WithSettings(settings setting.Settings) LoggerOpt

WithSettings initialises the logger to use the settings. Via the settings the logger's level and other properties are controlled dynamically at run time.

type LokiHandler ¶

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

func NewLokiHandler ¶

func NewLokiHandler(opt *LokiHandlerOptions) *LokiHandler

NewLokiHandler use this handler only for local development!

Its purpose is to mimic your production setting in case you're using loki & grafana. It ships your logs to a local loki instance, so you can use the same setup for development. It does not care about performance, as in production you would log to `stdout` and the container-runtime's drivers (docker, kubernetes) or something will ship your logs to loki.

func (*LokiHandler) Enabled ¶

func (l *LokiHandler) Enabled(_ context.Context, _ slog.Level) bool

func (*LokiHandler) Handle ¶

func (l *LokiHandler) Handle(ctx context.Context, record slog.Record) error

func (*LokiHandler) WithAttrs ¶

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

func (*LokiHandler) WithGroup ¶

func (l *LokiHandler) WithGroup(name string) slog.Handler

type LokiHandlerOptions ¶

type LokiHandlerOptions struct {
	Labels  map[string]string
	PushURL string
}

type PostgresHandler ¶

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

func NewPostgresHandler ¶

func NewPostgresHandler(pgx *pgxpool.Pool, opt *PostgresHandlerOptions) *PostgresHandler

NewPostgresHandler use this handler in low traffic situations to inspect logs via the arrower admin Context. All logs older than 30 days are deleted when this handler is constructed, so the database stays pruned. In case pgx is nil the handler returns nil.

func (*PostgresHandler) Enabled ¶

func (l *PostgresHandler) Enabled(_ context.Context, _ slog.Level) bool

func (*PostgresHandler) Handle ¶

func (l *PostgresHandler) Handle(ctx context.Context, record slog.Record) error

func (*PostgresHandler) WithAttrs ¶

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

func (*PostgresHandler) WithGroup ¶

func (l *PostgresHandler) WithGroup(name string) slog.Handler

type PostgresHandlerOptions ¶

type PostgresHandlerOptions struct {
	// MaxBatchSize is the maximum number of logs kept before they are saved to the DB.
	// If the maximum is reached before the timeout the batch is transmitted.
	MaxBatchSize int
	// MaxTimeout is the maximum idle time before a batch is saved to the DB, even if
	// it didn't reach the maximum size yet.
	MaxTimeout time.Duration
}

PostgresHandlerOptions configures the PostgresHandler.

type TestLogger ¶

type TestLogger struct {
	*slog.Logger
	// contains filtered or unexported fields
}

TestLogger is a special logger for unit testing. It exposes all methods of slog and alog and can be injected as a logger dependency.

Additionally, TestLogger exposes a set of assertions on all the lines logged with this logger.

func Test ¶

func Test(t *testing.T) *TestLogger

Test returns a logger tuned for unit testing. It exposes a lot of log-specific assertions for the use in tests. The interface follows stretchr/testify as close as possible.

• Every assert func returns a bool indicating whether the assertion was successful or not, this is useful for if you want to go on making further assertions under certain conditions.

func (*TestLogger) Contains ¶

func (l *TestLogger) Contains(contains string, msgAndArgs ...any) bool

Contains asserts that at least one line contains the given substring contains.

func (*TestLogger) Empty ¶

func (l *TestLogger) Empty(msgAndArgs ...any) bool

Empty asserts that the logger has no lines logged.

func (*TestLogger) Level ¶

func (l *TestLogger) Level() slog.Level

func (*TestLogger) Lines ¶

func (l *TestLogger) Lines() []string

func (*TestLogger) NotContains ¶

func (l *TestLogger) NotContains(notContains string, msgAndArgs ...any) bool

NotContains asserts that no line of the log output contains the given substring notContains.

func (*TestLogger) NotEmpty ¶

func (l *TestLogger) NotEmpty(msgAndArgs ...any) bool

NotEmpty asserts that the logger has at least one line.

func (*TestLogger) SetLevel ¶

func (l *TestLogger) SetLevel(level slog.Level)

func (*TestLogger) String ¶

func (l *TestLogger) String() string

String return the complete log output of ech line logged to TestLogger.

func (*TestLogger) Total ¶

func (l *TestLogger) Total(total int, msgAndArgs ...any) bool

Total asserts that the logger has exactly total number of lines logged.

func (*TestLogger) UsesSettings ¶

func (l *TestLogger) UsesSettings() bool

Source Files ¶

arrower-logger.go logger.go loki-handler.go noop-handler.go postgres-handler.go testing.go

Directories ¶