logger

package
v0.6.2 Latest Latest
Warning

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

 Go to latest Published: Apr 21, 2023 License: MIT Imports: 13 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 CurrentCaller added in v0.5.0 

func CurrentCaller() string

CurrentCaller retrieves the caller for the caller of CurrentCaller, formatted for using as a value in LogContext.Caller. 

 myFunc() { 		<- returns this caller
		func() {
			CurrentCaller()
		}()
 }

func WithEnv added in v0.3.7 

func WithEnv(env string) func(*TrailsLogger)

WithEnv sets the environment *TrailsLogger is operating in.

func WithLevel added in v0.3.7 

func WithLevel(level LogLevel) func(*TrailsLogger)

WithLevel sets the log level *TrailsLogger uses.

func WithLogger added in v0.3.7 

func WithLogger(log *log.Logger) func(*TrailsLogger)

WithLogger sets the *log.Logger *TrailsLogger uses.

func WithSkip added in v0.4.2 

func WithSkip(skip int) func(*TrailsLogger)

WithSkip sets the number of frames in the call stack to skip in order to log the desired file and line number of the calling code.

Types

type LogContext added in v0.3.7 

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

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

type LogLevel int
const (
	LogLevelUnk LogLevel = iota
	LogLevelDebug
	LogLevelInfo
	LogLevelWarn
	LogLevelError
	LogLevelFatal
)

func NewLogLevel added in v0.3.7 

func NewLogLevel(val string) LogLevel

NewLogLevel translates val into a LogLevel. The string representation ought to be all uppercase; e.g., DEBUG, WARN.

func (LogLevel) String added in v0.3.7 

func (ll LogLevel) String() string

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 {
	Debug(msg string, ctx *LogContext)
	Error(msg string, ctx *LogContext)
	Fatal(msg string, ctx *LogContext)
	Info(msg string, ctx *LogContext)
	Warn(msg string, ctx *LogContext)

	LogLevel() LogLevel
}

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

func New added in v0.4.2 

func New(opts ...LoggerOptFn) Logger

New constructs a TrailsLogger.

Logs are printed to os.Stdout by default, using the std lib log pkg. The default environment is DEVELOPMENT. The default log level is DEBUG.

func NewSentryLogger added in v0.3.7 

func NewSentryLogger(tl *TrailsLogger, dsn string) Logger

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

type LoggerOptFn added in v0.3.7 

type LoggerOptFn func(*TrailsLogger)

A LoggerOptFn is a functional option configuring a *TrailsLogger when constructing a new one.

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) SkipLogger

AddSkip replaces the current number of frames to scroll back when logging a message.

Use *SentryLogger.Skip to get the current skip amount when needing to add to it with AddSkip.

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

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

Fatal writes a fatal 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) LogLevel added in v0.3.7 

func (sl *SentryLogger) LogLevel() LogLevel

LogLevel returns the LogLevel set for the SentryLogger.

Use WithLevel to set the log level on app startup.

func (*SentryLogger) Skip added in v0.4.2 

func (sl *SentryLogger) Skip() int

Skip returns the current amount of frames to scroll back when logging a message.

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

type SkipLogger interface {
	AddSkip(i int) SkipLogger
	Skip() int
	Logger
}

The SkipLogger interface defines a Logger that scrolls back the number of frames provided in order to ascertain the call site.

type TrailsLogger 

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

TrailsLogger implements Logger using *log.Logger.

func (*TrailsLogger) AddSkip added in v0.4.2 

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

AddSkip replaces the current number of frames to scroll back when logging a message.

Use Skip to get the current skip amount when needing to add to it with AddSkip.

func (*TrailsLogger) Debug 

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

Debug writes a debug log.

func (*TrailsLogger) Error 

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

Error writes an error log.

func (*TrailsLogger) Fatal 

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

Fatal writes a fatal log.

func (*TrailsLogger) Info 

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

Info writes an info log.

func (*TrailsLogger) LogLevel added in v0.3.7 

func (l *TrailsLogger) LogLevel() LogLevel

LogLevel returns the LogLevel set for the TrailsLogger.

func (*TrailsLogger) Skip added in v0.4.2 

func (l *TrailsLogger) Skip() int

Skip returns the current amount of frames to scroll back when logging a message.

func (*TrailsLogger) Warn 

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

Warn writes a warning log.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.