logger

package
v0.9.5 Latest Latest
Warning

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

Go to latest
Published: Oct 5, 2023 License: MIT Imports: 16 Imported by: 4

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func ColorizeLevel added in v0.7.0

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

ColorizeLevel adds color to the log level!

func DeleteLevelAttr added in v0.7.0

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

DeleteLevelAttr removes the log level from output.

func DeleteMessageAttr added in v0.7.0

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

DeleteMessageAttr removes the message from output.

func FlushSentry added in v0.7.0

func FlushSentry(_ context.Context) error

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

func TruncSourceAttr added in v0.7.0

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 added in v0.3.7

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 added in v0.7.0

func (lc LogContext) LogValue() slog.Value

func (LogContext) MarshalText added in v0.3.7

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 added in v0.3.7

func (lc LogContext) String() string

String stringifies LogContext as a JSON representation of it.

type LogUser added in v0.3.7

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 added in v0.4.2

func New(log *slog.Logger) Logger

New constructs a Logger using log/slog.Logger.

func NewSentryLogger added in v0.3.7

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 added in v0.3.7

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 added in v0.4.2

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

func (*SentryLogger) Debug added in v0.3.7

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

Debug writes a debug log.

func (*SentryLogger) Error added in v0.3.7

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

Error writes an error log and sends it to Sentry.

func (*SentryLogger) Info added in v0.3.7

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

Info writes an info log.

func (*SentryLogger) Skip added in v0.4.2

func (sl *SentryLogger) Skip() int

func (*SentryLogger) Unwrap added in v0.7.0

func (sl *SentryLogger) Unwrap() Logger

Unwrap exposes the underlying Logger backing the *SentryLogger.

func (*SentryLogger) Warn added in v0.3.7

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 log/slog.Logger.

func (*TrailsLogger) AddSkip added in v0.4.2

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 added in v0.4.2

func (l *TrailsLogger) Skip() int

func (*TrailsLogger) Warn

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

Jump to

Keyboard shortcuts

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