README
¶
Logging
- Overview
- Logged Events
- Usage
- Framework
- External Configuration
- Custom Configuration
- Native Support
- Legacy Support
Overview
Sysl-go comes equipped with flexible, out-of-the-box logging support. The following sections describe what gets logged and how the logger can be configured and utilised within custom code.
Logged Events
Sysl-go logs the following major categories and fields:
Error Events
Sysl-go logs all errors encountered within the running on an application. Examples include timeout errors, marshalling errors and errors encountered in custom code.
Info Events
Sysl-go logs all information for the purpose of understanding the state of the application and its requests. Examples include the server configuration on startup and the state of upstream and downstream requests.
Debug Events
Sysl-go logs verbose information for the purpose of debugging. Examples include JWT authorisation failures and request and response payloads (see External Configuration below).
Event Fields
Sysl-go includes attaches additional field values to some of its logs. The following notable fields are attached:
| Field | Details |
|---|---|
traceid |
HTTP: Identifier retrieved from RequestID header or uniqely generated for the purpose of tracing a request. |
remote |
HTTP: The remote address of a downstream request. |
latency |
The time required to fulfil a request. |
Errors
Sysl-go logs all errors encountered within the running on an application.
Usage
Sysl-go utilises the context.Context to store the logger for use throughout the application.
Anywhere that a context can be found, a log can be sent to the centralised logger:
import ( "github.com/anz-bank/sysl-go/log" )
log.Info(ctx, "Hello world")
In some instances it is desirable to attach additional information to all logs that utilise a given context:
ctx = log.WithStr(ctx, "server_name", "great_pineapple")
log.Info(ctx, "Server started") // Log includes server name
...
ctx = log.WithInt(ctx, "request_id", request.id)
log.Info(ctx, "Request received") // Log includes both server name and request id
Framework
Sysl-go respects that different teams want to use different logging solutions and that Sysl-go shouldn't prevent you from doing as such.
In order to achieve this, the logging framework within Sysl-go is designed around the log.Logger interface that acts as a wrapper around concrete logging implementations.
Out-of-the-box Sysl-go supports the following logging implementations:
By default, the Pkg logger is used within Sysl-go. To use a different logger or to configure the logger beyond the log level, see Custom Configuration below.
External Configuration
Sysl-go applications are configured through an external configuration file. The logger can be configured to record logs at or above a particular level:
library:
log:
level: debug # one of error, info, debug
Another configurable value provides the ability to log the contents of requests and responses:
library:
log:
logPayload: true # include payload contents in log messages
Custom Configuration
By default, the Pkg logger is used within Sysl-go.
To use a different logger or to configure the logger beyond the log level, add a custom Logger hook to the Hooks structure that builds and returns a customised logger.
The following example demonstrates the use of a customised Logrus logger:
func newAppServer(ctx context.Context) (core.StoppableServer, error) {
return example.NewServer(ctx,
func(ctx context.Context, config AppConfig) (*example.ServiceInterface, *core.Hooks, error) {
return &gateway.ServiceInterface{
...
}, &core.Hooks{
Logger: func() log.Logger {
logger := logrus.New()
logger.Formatter = &logrus.JSONFormatter{}
return anzlog.NewLogrusLogger(logger)
}
}, nil
},
)
}
The returned logger will have the log level applied from the configuration file by Sysl-go internally.
Native Support
Some logging implementations provide their own mechanism to interact with the context.Context.
For example, the Pkg logger can be used directly:
import ( pkglog "github.com/anz-bank/pkg/log" )
ctx = pkglog.With("key", "value").Onto(ctx)
pkglog.Info(ctx, "Hello world")
The Sysl-go logging framework understands this and so the implementation works seamlessly whether you access the logger natively or through the wrapper:
import (
pkglog "github.com/anz-bank/pkg/log"
"github.com/anz-bank/sysl-go/log"
)
ctx = pkglog.With("key", "value").Onto(ctx) // Put a key/value into the context
pkglog.Info(ctx, "Native") // Native call, includes key/value pair
log.Info(ctx, "Wrapped") // Wrapped call, also includes key/value pair
Legacy Support
Sysl-go has gone through two iterations of logging. The first iteration enforced the use of Logrus. The second iteration replaced Logrus with the Pkg logger, providing a hook mechanism to route logs back through Logrus for backwards compatibility.
With the introduction of the new logging framework, backwards compatible support of both Logrus and the Pkg logger is provided seamlessly, however upgrading to the approach described in the Custom Configuration is recommended:
Logrus
import (
"github.com/sirupsen/logrus"
"github.com/anz-bank/sysl-go/log"
)
ctx := common.LoggerToContext(ctx, logrus.New(), nil) // Put the logger in the context (the legacy approach)
example.NewServer(ctx, ...) // Initialise the server
...
logger := common.GetLoggerFromContext(ctx) // Retrieve the logger from the context
logger.Info(ctx, "Native") // Log natively
log.Info(ctx, "Wrapped") // Log using the wrapper (uses the same Logrus instance)
Pkg logger
import (
pkglog "github.com/anz-bank/pkg/log"
"github.com/anz-bank/sysl-go/log"
)
ctx = pkglog.With("key", "value").Onto(ctx) // Initialise the pkg logger (the legacy approach)
example.NewServer(ctx, ...) // Initialise the server
...
pkglog.Info(ctx, "Native") // Log natively
log.Info(ctx, "Wrapped") // Log using the wrapper (uses the same pkg values)
Documentation
¶
Index ¶
- Constants
- func Debug(ctx context.Context, message string)
- func Debugf(ctx context.Context, format string, args ...interface{})
- func Error(ctx context.Context, err error, message string)
- func Errorf(ctx context.Context, err error, format string, args ...interface{})
- func GetLogrusLogEntryFromContext(ctx context.Context) *logrus.Entrydeprecated
- func GetLogrusLoggerFromContext(ctx context.Context) *logrus.Loggerdeprecated
- func Info(ctx context.Context, message string)
- func Infof(ctx context.Context, format string, args ...interface{})
- func LogrusLoggerToContext(ctx context.Context, logger *logrus.Logger, entry *logrus.Entry) context.Contextdeprecated
- func PutLogger(ctx context.Context, logger Logger) context.Context
- func WithDuration(ctx context.Context, key string, value time.Duration) context.Context
- func WithInt(ctx context.Context, key string, value int) context.Context
- func WithLevel(ctx context.Context, level Level) context.Context
- func WithStr(ctx context.Context, key string, value string) context.Context
- type Level
- type Logger
Constants ¶
const ( ErrorLevel = Level(logrus.ErrorLevel) // 2 InfoLevel = Level(logrus.InfoLevel) // 4 DebugLevel = Level(logrus.DebugLevel) // 5 )
Variables ¶
This section is empty.
Functions ¶
func GetLogrusLogEntryFromContext
deprecated
func GetLogrusLoggerFromContext
deprecated
func WithDuration ¶
WithDuration returns the given context with a logger that persists the given key/value.
Types ¶
type Level ¶
type Level int
Level represents the level at which a logger will log. The currently supported values are: 2 - Error 4 - Info 5 - Debug.
type Logger ¶
type Logger interface {
Error(err error, message string)
Info(message string)
Debug(message string)
// WithStr returns a new logger that persists the given key/value.
WithStr(key string, value string) Logger
// WithInt returns a new logger that persists the given key/value.
WithInt(key string, value int) Logger
// WithDuration returns a new logger that persists the given key/value.
WithDuration(key string, value time.Duration) Logger
// WithLevel returns a new logger that logs the given level or below.
WithLevel(level Level) Logger
// Inject puts the logger into the context, returning the new context and a function that
// can be later used to restore the logger from the context.
Inject(ctx context.Context) (context.Context, func(ctx context.Context) Logger)
}
Logger is a component used to perform logging.
func NewDefaultLogger ¶
func NewDefaultLogger() Logger
NewDefaultLogger returns a logger that is regarded as the default logger to use within an application when no logger configuration is provided.
func NewLogrusLogger ¶
NewLogrusLogger returns an implementation of Logger that uses the Logrus logger.
func NewPkgLogger ¶
NewPkgLogger returns is an implementation of Logger that uses the pkg/log logger.
func NewZeroPkgLogger ¶
NewZeroPkgLogger returns is an implementation of Logger that uses the pkg/logging logger.
Source Files