logger

README

package logger

Package logger provides tooling for structured logging. With logger, you can use context to add logging details to your call stack.

How to use

ctx := context.Background()

// You can add details to the context; thus, every logging call using this context will inherit the details.
ctx = logger.ContextWithDetails(ctx, logger.Details{
    "foo": "bar",
    "baz": "qux",
})

// You can use your own Logger instance or the logger.Default logger instance if you plan to log to the STDOUT. 
logger.Info(ctx, "foo", logger.Details{
    "userID":    42,
    "accountID": 24,
})

example output:

{"accountID":24,"baz":"qux","foo":"bar","level":"info","message":"foo","timestamp":"2023-02-24T02:11:33+01:00","userID":42}

How to configure:

logger.Logger can be configured through its struct fields; please see the documentation for more details. To configure the default logger, simply configure it from your main.

func main() {
    logger.Default.MessageKey = "msg"
}

Documentation

Overview

Package logger provides tooling for structured logging. With logger, you can use context to add logging details to your call stack.

Example (WithDetails)

package main

import (
	"context"
	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	ctx := context.Background()
	logger.Info(ctx, "foo", logger.Details{
		"userID":    42,
		"accountID": 24,
	})
}

Index

• func ContextWithDetails(ctx context.Context, details Details) context.Context
• func Debug(ctx context.Context, msg string, ds ...Details)
• func Error(ctx context.Context, msg string, ds ...Details)
• func Fatal(ctx context.Context, msg string, ds ...Details)
• func Info(ctx context.Context, msg string, ds ...Details)
• func Stub(tb testingTB) *bytes.Buffer
• func Warn(ctx context.Context, msg string, ds ...Details)
• type Details
  • func (ld Details) Err(err error) Details
  • func (ld Details) Merge(oth Details) Details
• type Logger
  • func (l Logger) Debug(ctx context.Context, msg string, ds ...Details)
  • func (l Logger) Error(ctx context.Context, msg string, ds ...Details)
  • func (l Logger) Fatal(ctx context.Context, msg string, ds ...Details)
  • func (l Logger) Info(ctx context.Context, msg string, ds ...Details)
  • func (l Logger) Warn(ctx context.Context, msg string, ds ...Details)

Examples

• Package (WithDetails)
• ContextWithDetails
• Debug
• Details.Err
• Error
• Fatal
• Info
• Stub
• Warn

Functions

func ContextWithDetails

func ContextWithDetails(ctx context.Context, details Details) context.Context

Example

package main

import (
	"context"
	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	ctx := context.Background()

	ctx = logger.ContextWithDetails(ctx, logger.Details{
		"foo": "bar",
		"baz": "qux",
	})

	logger.Info(ctx, "message") // will have details from the context
}

func Debug

func Debug(ctx context.Context, msg string, ds ...Details)

Example

package main

import (
	"context"
	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	ctx := context.Background()
	logger.Debug(ctx, "foo")
}

func Error

func Error(ctx context.Context, msg string, ds ...Details)

Example

package main

import (
	"context"
	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	ctx := context.Background()
	logger.Error(ctx, "foo")
}

func Fatal

func Fatal(ctx context.Context, msg string, ds ...Details)

Example

package main

import (
	"context"
	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	ctx := context.Background()
	logger.Fatal(ctx, "foo")
}

func Info

func Info(ctx context.Context, msg string, ds ...Details)

Example

package main

import (
	"context"
	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	ctx := context.Background()
	logger.Info(ctx, "foo")
}

func Stub

func Stub(tb testingTB) *bytes.Buffer

Stub the logger.Default and return the buffer where the logging output will be recorded. Stub will restore the logger.Default after the test.

Example

package main

import (
	"github.com/adamluzsi/frameless/pkg/logger"
	"strings"
	"testing"
)

func main() {
	var tb testing.TB
	buf := logger.Stub(tb) // stub will clean up after itself when the test is finished
	logger.Info(nil, "foo")
	strings.Contains(buf.String(), "foo") // true
}

func Warn

func Warn(ctx context.Context, msg string, ds ...Details)

Example

package main

import (
	"context"
	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	ctx := context.Background()
	logger.Warn(ctx, "foo")
}

Types

type Details

type Details map[string]any

func (Details) Err

func (ld Details) Err(err error) Details

Example

package main

import (
	"context"
	"errors"
	"github.com/adamluzsi/frameless/pkg/logger"
)

func main() {
	ctx := context.Background()
	err := errors.New("boom")

	logger.Error(ctx, "task failed successfully", logger.Details{}.Err(err))
}

func (Details) Merge

func (ld Details) Merge(oth Details) Details

type Logger

type Logger struct {
	Out io.Writer

	Separator string

	MessageKey   string
	LevelKey     string
	TimestampKey string

	// MarshalFunc is used to serialise the logging message event.
	// When nil it defaults to JSON format.
	MarshalFunc func(any) ([]byte, error)
}

var Default Logger

func (Logger) Debug

func (l Logger) Debug(ctx context.Context, msg string, ds ...Details)

func (Logger) Error

func (l Logger) Error(ctx context.Context, msg string, ds ...Details)

func (Logger) Fatal

func (l Logger) Fatal(ctx context.Context, msg string, ds ...Details)

func (Logger) Info

func (l Logger) Info(ctx context.Context, msg string, ds ...Details)

func (Logger) Warn

func (l Logger) Warn(ctx context.Context, msg string, ds ...Details)