logging

Documentation

Overview

Package logging provides a kitlog compatible logger.

This package is mostly a thin wrapper around kitlog (http://github.com/go-kit/log). kitlog provides a minimalist, contextual, fully composable logger. However, it is too unopinionated, hence requiring some efforts and coordination to set up a good practise.

Integration

Package logging is bundled in core. Enable logging as dependency by calling:

var c *core.C = core.New()
c.ProvideEssentials()

See example for usage.

Example (Level)

package main

import (
	"github.com/DoNewsCode/core/logging"

	"github.com/go-kit/log/level"
)

func main() {
	logger := logging.NewLogger("json")
	level.Info(logger).Log("foo", "bar")
}

Output:

{"foo":"bar","level":"info"}

Example (Minimal)

package main

import (
	"github.com/DoNewsCode/core/logging"
)

func main() {
	logger := logging.NewLogger("json")
	logger.Log("foo", "bar")
}

Output:

{"foo":"bar"}

Example (Sprintf)

package main

import (
	"fmt"

	"github.com/DoNewsCode/core/logging"

	"github.com/go-kit/log/level"
)

func main() {
	logger := logging.NewLogger("json")
	// Set log level to info
	logger = level.NewFilter(logger, level.AllowInfo())
	levelLogger := logging.WithLevel(logger)

	// Let's try to log some debug messages. They are filtered by log level, so you should see no output.
	// The cost of fmt.Sprintf is paid event if the log is filtered out. This sometimes can be a huge performance downside.
	levelLogger.Debugw("record some data", "data", fmt.Sprintf("%+v", []int{1, 2, 3}))
	// Or better, we can use logging.Sprintf to avoid the cost if the log is not actually written to the output.
	levelLogger.Debugw("record some data", "data", logging.Sprintf("%+v", []int{1, 2, 3}))

}

Index

• func LevelFilter(levelCfg string) level.Option
• func NewLogger(format string) (logger log.Logger)
• func Sprint(args ...any) fmt.Stringer
• func Sprintf(format string, args ...any) fmt.Stringer
• func WithBaggage(logger log.Logger, ctx context.Context) log.Logger
• func WithContext(logger log.Logger, ctx context.Context) log.Logger
• type LevelLogger
  • func WithLevel(logger log.Logger) LevelLogger

Examples

• Package (Level)
• Package (Minimal)
• Package (Sprintf)
• WithContext
• WithLevel

Functions

func LevelFilter

func LevelFilter(levelCfg string) level.Option

LevelFilter filters the log output based on its level. Allowed levels are "debug", "info", "warn", "error", or "none"

func NewLogger

func NewLogger(format string) (logger log.Logger)

NewLogger constructs a log.Logger based on the given format. The support formats are "json" and "logfmt".

func Sprint

func Sprint(args ...any) fmt.Stringer

Sprint returns a log entry that is formatted using fmt.Sprint just before writing to the output. This is more desirable than using fmt.Sprint from the caller's end because the cost of formatting can be avoided if the log is filtered, for example, by log level.

func Sprintf

func Sprintf(format string, args ...any) fmt.Stringer

Sprintf returns a log entry that is formatted using fmt.Sprintf just before writing to the output. This is more desirable than using fmt.Sprintf from the caller's end because the cost of formatting can be avoided if the log is filtered, for example, by log level.

func WithBaggage

func WithBaggage(logger log.Logger, ctx context.Context) log.Logger

WithBaggage decorates the log.Logger with information form context.

func WithContext

func WithContext(logger log.Logger, ctx context.Context) log.Logger

WithContext decorates the log.Logger with information form context. If there is an opentracing span in the context, the span will receive the logger output as well.

Example

package main

import (
	"context"

	"github.com/DoNewsCode/core/ctxmeta"
	"github.com/DoNewsCode/core/logging"
)

func main() {
	bag, ctx := ctxmeta.Inject(context.Background())
	bag.Set("clientIp", "127.0.0.1")
	bag.Set("requestUrl", "/example")
	bag.Set("transport", "http")
	logger := logging.NewLogger("json")
	ctxLogger := logging.WithContext(logger, ctx)
	ctxLogger.Log("foo", "bar")
}

Output:

{"clientIp":"127.0.0.1","foo":"bar","requestUrl":"/example","transport":"http"}

Types

type LevelLogger

type LevelLogger = contract.LevelLogger

LevelLogger is an alias of contract.LevelLogger

func WithLevel

func WithLevel(logger log.Logger) LevelLogger

WithLevel decorates the logger and returns a contract.LevelLogger.

Note: Don't inject contract.LevelLogger to dependency consumers directly as this will weaken the powerful abstraction of log.Logger. Only inject log.Logger, and converts log.Logger to contract.LevelLogger within the boundary of dependency consumer if desired.

Example

package main

import (
	"github.com/DoNewsCode/core/logging"
)

func main() {
	logger := logging.NewLogger("json")
	levelLogger := logging.WithLevel(logger)
	levelLogger.Info("hello")
}

Output:

{"caller":"example_test.go:30","level":"info","msg":"hello"}