log package

The gosoline logger is based upon a simple interface that uses handlers internally to enable fully customizable log handling.

Function

NewLogger()

Usage

logger := log.NewLoggerWithInterfaces(myClock, []log.Handler{handler1, handler2})

Description

Create a logger with with no handlers and a real time clock. This provides an extended interface, including the Option(opt ...Option) error function to change the behaviour of the logger.

NewLoggerWithInterfaces()

Usage

logger := log.NewLoggerWithInterfaces(myClock, []log.Handler{handler1, handler2})

Description

Provide a clock and some handlers when you create a new logger. Like NewLogger(), this provides an extended interface, including the Option(opt ...Option) error function to change the behaviour of the logger.

InitContext()

Usage

ctx = log.InitContext(ctx)

Description

Return a new context capable of carrying (mutable) local and global logger fields.

AppendContextFields()

Usage

localCtx := log.AppendContextFields(ctx, map[string]any{
  "field": "value",
})

Description

Appends fields to the existing local context fields, creating and returning a new context containing the merged fields.

caution

Any existing fields with the same key as any new field provided will be overwritten.

Related methods

MutateContextFields()

Mutates local context fields if the context already contains fields which can be mutated. Otherwise, it initializes a new context able to carry fields in the future.

localCtx = log.MutateContextFields(localCtx, map[string]any{
    "field": "new_value",
})

AppendGlobalContextFields()

Appends fields to the existing global context fields, creating a new context containing the merged fields.

localCtx = log.AppendGlobalContextFields(globalCtx, map[string]any{
    "field": "new_value",
})

MutateGlobalContextFields()

Mutates global context fields if the context already contains fields which can be mutated. Otherwise, it initializes a new context able to carry fields in the future.

localCtx = log.MutateGlobalContextFields(globalCtx, map[string]any{
    "field": "new_value",
})

caution

Global fields override local fields when they have the same name.

ContextFieldsResolver()

Usage

localFields := log.ContextFieldsResolver(ctx)
print(localFields["field"])

Description

Extracts the local and global fields from a context and returns a map.

Related methods

GlobalContextFieldsResolver()

Extracts the global fields from a context and returns a map.

localFields := log.GlobalContextFieldsResolver(ctx)
print(localFields["field"])

Methods

Debug()

logger.Debug("Message")

Description

Logs a message at the Debug log level.

Related methods

Info()

logger.Info("Message")

Warn()

logger.Warn("Message")

Error()

logger.Error("Message")

WithContextFieldsResolver()

Usage

if err := logger.Option(log.WithContextFieldsResolver(log.ContextFieldsResolver)); err != nil {
    panic(err)
}

Description

Adds a context fields resolver to the logger.

WithFields()

Usage

loggerWithFields := logger.WithFields(log.Fields{
    "b": true,
})

Description

Adds global fields to the logger, which will be set on every log message.

WithHandlers()

Usage

    logHandler := log.NewHandlerIoWriter(log.LevelInfo, []string{}, log.FormatterConsole, "", os.Stdout)
    loggerOptions := []log.Option{
        log.WithHandlers(logHandler),
    }

Description

Adds additional handlers to the logger.

Interfaces

Handler

Definition

type Handler interface {
    Channels() []string
    Level() int
    Log(timestamp time.Time, level int, msg string, args []interface{}, err error, data Data) error
}

Description

• Channels() []string and Level() int are called on every log action to check if the handler should be applied.
• Log does the actual logging afterwards.

Log configurations

setting	description	default
log.level	default level for all handlers without an explicit level value	info
log.handlers	a map of handlers that will be called for every log message	every logger gets a 'main' handler by default if there is no other handler defined
log.handlers.X.type	defines the type of the handler	-

Built-in handlers

Gosoline has a couple of built-in handlers, which are ready to use out of the box:

iowriter

Multitool, which is able to write logs to everything which implements the io.Writer interface. Config options are:

Setting	Description	Default
level	Levels of this and higher priority will get logged	info
channels	Messages logged into these channels will be handled	[]
formatter	Which format should be used by this handler	console
timestamp_format	A golang time format string to control the format of the timestamp	15:04:05.000
writer	Which io.writer implementation to use	stdout

Log to STDOUT

log:
  handlers:
    main:
      type: iowriter
      level: info
      channels: []
      formatter: console
      timestamp_format: 15:04:05.000
      writer: stdout

Log to a file

log:
  handlers:
    main:
      type: iowriter
      level: info
      channels: *
      formatter: console
      timestamp_format: 15:04:05.000
      writer: file
      path: logs.log

Metric

No configuration needed. Writes a metric data point for every warn and error log.

Sentry

No configuration needed. Publishes every logged error to Sentry.