logger

Documentation

Overview

Package logger provides logging functionality to a trails app by defining the required behavior in Logger and providing an implementation of it with TrailsLogger.

Overview

The Logger interface outputs messages at certain levels of importance. LogLevel is the type to use to represent those levels. An implementation of Logger may be initialized at a certain [LogLevel] and only emit messages at or above that level of importance. For example, TrailsLogger accepts a [LogLevel], and if initialized with [LogLevelWarn], only *TrailsLogger.Warn, *TrailsLogger.Error, and [*TrailsLogger.Fatal] produce messages.

TrailsLogger

The TrailsLogger provides all the logging functionality needed for a trails app. It is the implementation of Logger returned by the New function.

Log messages emitted by TrailsLogger are composed of a few parts:

• timestamp
• log level
• call site
• message
• log context

Here's an example:

2022/04/28 15:55:21 [DEBUG] web/dashboard_handler.go:43 'such fun!' log_context: "{"user":"{"id": 1, "email": "trails@example.com"}}"

The file, line number, and parent directory of where a TrailsLogger comprise the call site. The message is the actual string passed into the TrailsLogger method, in this example, *TrailsLogger.Debug. Lastly, the log context is a JSON-encoded *LogContext. The last component allows for including additional data inessential to the message proper, but provides a fuller picture of the application state at the time of logging.

SkipLogger

Sometimes, especially with internal packages, the file and line number in a log needs to be configurable. [SkipLogger] provides additional configuration functionality by setting the number of frames to skip back in order to reach the desired caller.

For an example use case, review http/resp.

Index

• func ColorizeLevel(groups []string, a slog.Attr) slog.Attr
• func DeleteLevelAttr(groups []string, a slog.Attr) slog.Attr
• func DeleteMessageAttr(groups []string, a slog.Attr) slog.Attr
• func FlushSentry(_ context.Context) error
• func TruncSourceAttr(groups []string, a slog.Attr) slog.Attr
• type LogContext
  • func (lc LogContext) LogValue() slog.Value
  • func (lc LogContext) MarshalText() ([]byte, error)
  • func (lc LogContext) String() string
• type LogUser
• type Logger
  • func New(log *slog.Logger) Logger
  • func NewSentryLogger(env trails.Environment, l Logger, dsn string) Logger
• type SentryLogger
  • func (sl *SentryLogger) AddSkip(i int) Logger
  • func (sl *SentryLogger) Debug(msg string, ctx *LogContext)
  • func (sl *SentryLogger) Error(msg string, ctx *LogContext)
  • func (sl *SentryLogger) Info(msg string, ctx *LogContext)
  • func (sl *SentryLogger) Skip() int
  • func (sl *SentryLogger) Unwrap() Logger
  • func (sl *SentryLogger) Warn(msg string, ctx *LogContext)
• type TrailsLogger
  • func (l *TrailsLogger) AddSkip(i int) Logger
  • func (l *TrailsLogger) Debug(msg string, ctx *LogContext)
  • func (l *TrailsLogger) Error(msg string, ctx *LogContext)
  • func (l *TrailsLogger) Info(msg string, ctx *LogContext)
  • func (l *TrailsLogger) Skip() int
  • func (l *TrailsLogger) Warn(msg string, ctx *LogContext)

Functions

func ColorizeLevel

func ColorizeLevel(groups []string, a slog.Attr) slog.Attr

ColorizeLevel adds color to the log level!

func DeleteLevelAttr

func DeleteLevelAttr(groups []string, a slog.Attr) slog.Attr

DeleteLevelAttr removes the log level from output.

func DeleteMessageAttr

func DeleteMessageAttr(groups []string, a slog.Attr) slog.Attr

DeleteMessageAttr removes the message from output.

func FlushSentry

func FlushSentry(_ context.Context) error

FlushSentry is a ranger.ShutdownFn that calls sentry.Flush on app shutdown.

func TruncSourceAttr

func TruncSourceAttr(groups []string, a slog.Attr) slog.Attr

TruncSourceAttr truncates the full filepath of the source log call to a more-to-the-point path.

Types

type LogContext

type LogContext struct {
	// Caller overrides the caller file and line number with the PC.
	//
	// Caller is not logged in the text of a LogContext.
	//
	// Caller helps goroutines identify the callers of the process that spawned it.
	Caller uintptr

	// Data is any information pertinent at the time of the logging event.
	Data map[string]any

	// Error is the error that may or may not have instigated a logging event.
	Error error

	// Request is the *http.Request that may or may not have been open during the logging event.
	Request *http.Request

	// LogUser is the user whose session was active during the logging event.
	User LogUser
}

A LogContext provides additional information and configuration for a *logger.Logger method that cannot be tersely captured in the message itself.

func (LogContext) LogValue

func (lc LogContext) LogValue() slog.Value

func (LogContext) MarshalText

func (lc LogContext) MarshalText() ([]byte, error)

MarshalText converts LogContext into a JSON representation, eliminating zero-value fields or fields not requiring logging.

Values in LogContext.Data that cannot be represented in JSON will cause an error to be thrown.

MarshalText implements encoding.TextMarshaler.

func (LogContext) String

func (lc LogContext) String() string

String stringifies LogContext as a JSON representation of it.

type LogUser

type LogUser interface {
	// GetID retrieves the application's identifier for a user.
	GetID() uint

	// GetEmail retrieves the email address of the user.
	// If not available, an ID should be returned.
	GetEmail() string
}

LogUser is the interface exposing attributes of a user to a LogContext.

type Logger

type Logger interface {
	// AddSkip sets the number of stacktrace frames to ascend when
	// determining the file and line number of the log message.
	//
	// NB: AddSkip does not add to the amount set by previous AddSkip calls.
	// To add to it, do something like: l = l.AddSkip(l.Skip + i)
	AddSkip(i int) Logger

	// Skip returns the number of frames that not be included
	// when determining the file/line number of a call to a log message method.
	Skip() int

	// Debug writes a debug log message.
	Debug(msg string, ctx *LogContext)

	// Error writes an error log message.
	Error(msg string, ctx *LogContext)

	// Info writes an info log message.
	Info(msg string, ctx *LogContext)

	// Warn writes a warning log message.
	Warn(msg string, ctx *LogContext)
}

The Logger interface defines the ways of logging messages at certain levels of importance.

func New

func New(log *slog.Logger) Logger

New constructs a Logger using golang.org/x/exp/slog.Logger.

func NewSentryLogger

func NewSentryLogger(env trails.Environment, l Logger, dsn string) Logger

NewSentryLogger constructs a *SentryLogger based off the provided *TrailsLogger, routing messages to the DSN provided.

type SentryLogger

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

A SentryLogger logs messages and reports sufficiently important ones to error tracking software Sentry (https://sentry.io).

func (*SentryLogger) AddSkip

func (sl *SentryLogger) AddSkip(i int) Logger

func (*SentryLogger) Debug

func (sl *SentryLogger) Debug(msg string, ctx *LogContext)

Debug writes a debug log.

func (*SentryLogger) Error

func (sl *SentryLogger) Error(msg string, ctx *LogContext)

Error writes an error log and sends it to Sentry.

func (*SentryLogger) Info

func (sl *SentryLogger) Info(msg string, ctx *LogContext)

Info writes an info log.

func (*SentryLogger) Skip

func (sl *SentryLogger) Skip() int

func (*SentryLogger) Unwrap

func (sl *SentryLogger) Unwrap() Logger

Unwrap exposes the underlying Logger backing the *SentryLogger.

func (*SentryLogger) Warn

func (sl *SentryLogger) Warn(msg string, ctx *LogContext)

Warn writes a warning log and sends it to Sentry.

type TrailsLogger

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

TrailsLogger implements Logger using golang.org/x/exp/slog.Logger.

func (*TrailsLogger) AddSkip

func (l *TrailsLogger) AddSkip(i int) Logger

func (*TrailsLogger) Debug

func (l *TrailsLogger) Debug(msg string, ctx *LogContext)

func (*TrailsLogger) Error

func (l *TrailsLogger) Error(msg string, ctx *LogContext)

func (*TrailsLogger) Info

func (l *TrailsLogger) Info(msg string, ctx *LogContext)

func (*TrailsLogger) Skip

func (l *TrailsLogger) Skip() int

func (*TrailsLogger) Warn

func (l *TrailsLogger) Warn(msg string, ctx *LogContext)