logging

Documentation

Overview

Package logging implements a structured-log model with common functionalities and utility functions.

The log messages are augmented by default with additional fields to enrich the response with application metadata. The standard syslog levels are automatically mapped to the corresponding zap log levels.

It includes the following features:

• Default logger configuration with program name, version, and release.
• Custom logger configuration with additional fields.
• Context-based logging with component and method tags.
• Log level function hook for incrementing log metrics.
• Log sync function to flush the logger and ignore the error.
• Log close function to close an object and log an error in case of failure.

The package is designed to be used in conjunction with the go.uber.org/zap package.

This is a custom implementation of the configuration model described in the following article:

• Nicola Asuni, 2014-08-11, "Software Logging Format", https://technick.net/guides/software/software_logging_format/

Index

• Variables
• func Close(ctx context.Context, obj io.Closer, errorMessage string)
• func FromContext(ctx context.Context) *zap.Logger
• func NewDefaultLogger(name, version, release, format, level string) (*zap.Logger, error)
• func NewLogger(opts ...Option) (*zap.Logger, error)
• func NopLogger() *zap.Logger
• func ParseLevel(l string) (zapcore.Level, error)
• func Sync(s Syncer)
• func WithComponent(ctx context.Context, comp string) *zap.Logger
• func WithComponentAndMethod(ctx context.Context, comp, method string) *zap.Logger
• func WithLevelFunctionHook(l *zap.Logger, fn IncrementLogMetricsFunc) *zap.Logger
• func WithLogger(ctx context.Context, l *zap.Logger) context.Context
• type Format
  • func ParseFormat(f string) (Format, error)
• type IncrementLogMetricsFunc
• type Option
  • func WithErrorOutputPaths(paths []string) Option
  • func WithFields(f ...zap.Field) Option
  • func WithFormat(f Format) Option
  • func WithFormatStr(f string) Option
  • func WithIncrementLogMetricsFunc(fn IncrementLogMetricsFunc) Option
  • func WithLevel(l zapcore.Level) Option
  • func WithLevelStr(l string) Option
  • func WithOutputPaths(paths []string) Option
• type Syncer

Variables

var LogFatal = zap.L().Fatal

LogFatal calls the default fatal logger.

Functions

func Close

func Close(ctx context.Context, obj io.Closer, errorMessage string)

Close closes an object and logs an error in case of failure.

func FromContext

func FromContext(ctx context.Context) *zap.Logger

FromContext retrieves a logger instance form the given context.

func NewDefaultLogger

func NewDefaultLogger(name, version, release, format, level string) (*zap.Logger, error)

NewDefaultLogger configures a logger with the default fields.

func NewLogger

func NewLogger(opts ...Option) (*zap.Logger, error)

NewLogger configures a root logger for the application.

func NopLogger

func NopLogger() *zap.Logger

NopLogger returns a no operation logger.

func ParseLevel

func ParseLevel(l string) (zapcore.Level, error)

ParseLevel converts syslog standard levels to zap a log level.

func Sync

func Sync(s Syncer)

Sync flushes the given logger and ignores the error.

func WithComponent

func WithComponent(ctx context.Context, comp string) *zap.Logger

WithComponent creates a child logger with an extra "component" tag.

func WithComponentAndMethod

func WithComponentAndMethod(ctx context.Context, comp, method string) *zap.Logger

WithComponentAndMethod creates a child logger with extra "component" and "method" tags.

func WithLevelFunctionHook

func WithLevelFunctionHook(l *zap.Logger, fn IncrementLogMetricsFunc) *zap.Logger

WithLevelFunctionHook registers a function with a level string argument which will be called each time the Logger writes out an Entry.

func WithLogger

func WithLogger(ctx context.Context, l *zap.Logger) context.Context

WithLogger returns a new context with the given logger.

Types

type Format

type Format int8

Format represents the logging output format to adopt.

const (

	// ConsoleFormat will print the log in a human friendly format.
	ConsoleFormat Format

	// JSONFormat will print the log in a machine readable format.
	JSONFormat
)

func ParseFormat

func ParseFormat(f string) (Format, error)

ParseFormat converts a string to a log format.

type IncrementLogMetricsFunc

type IncrementLogMetricsFunc func(string)

IncrementLogMetricsFunc is a type alias for the logging metric function.

type Option

type Option func(*config) error

Option is a type alias for a function that configures the application logger.

func WithErrorOutputPaths

func WithErrorOutputPaths(paths []string) Option

WithErrorOutputPaths manually overrides the ErrorOutputPaths option.

func WithFields

func WithFields(f ...zap.Field) Option

WithFields add static fields to the logger.

func WithFormat

func WithFormat(f Format) Option

WithFormat manually overrides the environment log format.

func WithFormatStr

func WithFormatStr(f string) Option

WithFormatStr manually overrides the environment log format.

func WithIncrementLogMetricsFunc

func WithIncrementLogMetricsFunc(fn IncrementLogMetricsFunc) Option

WithIncrementLogMetricsFunc replaces the default log level metrics function.

func WithLevel

func WithLevel(l zapcore.Level) Option

WithLevel manually overrides the environment log level.

func WithLevelStr

func WithLevelStr(l string) Option

WithLevelStr manually overrides the environment log level.

func WithOutputPaths

func WithOutputPaths(paths []string) Option

WithOutputPaths manually overrides the OutputPaths option.

type Syncer

type Syncer interface {
	Sync() error
}

Syncer is an interface to allow the testing of log syncing.