logger

README

JSON based logger for golang

A simple and efficient JSON-based logging library for Go applications, designed for easy integration and observability. It provides structured logging with various levels, automatic trace context propagation, and customizable output to streamline log management and analysis.

[!IMPORTANT] This repository was migrated from github.

Please refer to github.com/iolave/go-logger for versions <= v1.0.1

Install

go get codeberg.org/mice1337/go-logger

Features

• JSON formatted logs for easy parsing and querying.
• Log levels to control log verbosity.
• Automatic inclusion of trace information from context via go-trace.
• Handles circular references in log data.
• Customizable log output with additional data.

Usage

Create a logger

// ...
import "codeberg.org/mice1337/go-logger"

// Creates a logger
logger := logger.New()

// Set name and version (optional, omitted from logs if empty)
logger.Name = "my-awesome-logger"
logger.Version = "1.0.0"

// Set level (optional, defaults to LEVEL_INFO)
if err := logger.SetLevel(logger.LEVEL_INFO); err != nil {
    // Handle error
}

Write logs

ctx := context.Background() // Or your request context

logger.Debug(ctx, "debug message")
// {"timestamp":1722216216,"level":"debug","name":"my-awesome-logger","version":"1.0.0","trace":{},"info":{},"msg":"debug message"}

logger.Info(ctx, "info message")
// {"timestamp":1722216216,"level":"info","name":"my-awesome-logger","version":"1.0.0","trace":{},"info":{},"msg":"info message"}

logger.Warn(ctx, "warn message", errors.New("something happened"))
// {"timestamp":1722216216,"level":"warn","name":"my-awesome-logger","version":"1.0.0","trace":{},"error":{},"info":{},"msg":"warn message"}

logger.Error(ctx, "error message", errors.New("something bad happened"))
// {"timestamp":1722216216,"level":"error","name":"my-awesome-logger","version":"1.0.0","trace":{},"error":{},"info":{},"msg":"error message"}

logger.Fatal(ctx, "fatal message", errors.New("something terrible happened"))
// Exits the application after logging
// {"timestamp":1722216216,"level":"fatal","name":"my-awesome-logger","version":"1.0.0","trace":{},"error":{},"info":{},"msg":"fatal message"}

With trace information

The logger will automatically include trace information from the context if it's provided via go-trace.

import (
	"context"
	"errors"

	"codeberg.org/mice1337/go-logger"
	"codeberg.org/mice1337/go-trace"
)

// ...

// Create a new trace
t := trace.Trace{}
t.Set("trace_id", "my-trace-id")
t.Set("span_id", "my-span-id")

// Add the trace to the context
ctx := t.SetInContext(context.Background())

// Log a message with the context
logger.Info(ctx, "This log includes trace information")
// {"timestamp":1722216216,"level":"info","name":"my-awesome-logger","version":"1.0.0","trace":{"trace_id":"my-trace-id","span_id":"my-span-id"},"info":{},"msg":"This log includes trace information"}

Mock logger for testing

For testing, create a mock logger that implements the Logger interface but performs no operations.

import "codeberg.org/mice1337/go-logger"

// Create mock logger
l := logger.NewMock()

Schema version: v1.0.0

Log entry schema

Field	Description	JSON type
timestamp	Unix time	number
level	Log entry level	string
name	Name of the app/logger (optional, omitted if empty)	string
version	Version of the app/logger (optional, omitted if empty)	string
trace	Trace information from context	object
error	Error information	object
info	Custom data in any form or shape	object
msg	Log message	string

Log level definition

Level	Name
60	fatal
50	error
40	warn
30	info
20	debug
10	trace

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue.

Development

To get started with development, you'll need Go installed.

1. Fork the repository.
2. Clone your fork: git clone https://codeberg.org/YOUR_USERNAME/go-logger.git
3. Create a new branch: git checkout -b my-feature-branch
4. Make your changes.
5. Run tests: make test
6. Push to your branch: git push origin my-feature-branch
7. Open a pull request.

Documentation

Overview

go-coverage:ignore

Index

• type Config
• type Entry
• type GenericLogger
  • func New() *GenericLogger
  • func (l GenericLogger) Debug(ctx context.Context, msg string)
  • func (l GenericLogger) DebugWithData(ctx context.Context, msg string, info map[string]any)
  • func (l GenericLogger) Error(ctx context.Context, msg string, err error)
  • func (l GenericLogger) ErrorWithData(ctx context.Context, msg string, err error, info map[string]any)
  • func (l GenericLogger) Fatal(ctx context.Context, msg string, err error)
  • func (l GenericLogger) FatalWithData(ctx context.Context, msg string, err error, info map[string]any)
  • func (l GenericLogger) Info(ctx context.Context, msg string)
  • func (l GenericLogger) InfoWithData(ctx context.Context, msg string, info map[string]any)
  • func (l *GenericLogger) SetLevel(level Level) error
  • func (l GenericLogger) Trace(ctx context.Context, msg string)
  • func (l GenericLogger) TraceWithData(ctx context.Context, msg string, info map[string]any)
  • func (l GenericLogger) Warn(ctx context.Context, msg string, err error)
  • func (l GenericLogger) WarnWithData(ctx context.Context, msg string, err error, info map[string]any)
• type Level
  • func NewLevelFromString(s string) (Level, error)
  • func (l Level) IsValid() bool
  • func (l Level) String() string
• type Logger
  • func NewMock() Logger

Types

type Config

type Config struct {
	// Level is the level of the logger.
	Level Level
}

Config is the configuration of the logger.

type Entry

type Entry struct {
	Timestamp int64          `json:"timestamp"`
	Level     Level          `json:"-"`
	LevelStr  string         `json:"level"`
	Name      string         `json:"name,omitempty"`
	Version   string         `json:"version,omitempty"`
	Trace     trace.Trace    `json:"trace"`
	Error     error          `json:"error,omitempty"`
	Info      map[string]any `json:"info"`
	Msg       string         `json:"msg"`
}

Entry is the json representation of a log entry.

type GenericLogger

type GenericLogger struct {

	// Name is the name of the app.
	//
	// When using the [New] function, it is set to the empty
	// string. If it is set to a non-empty string, it is not
	// serialized in the logs.
	Name string

	// Version is the version of the app.
	//
	// When using the [New] function, it is set to the empty
	// string. If it is set to a non-empty string, it is not
	// serialized in the logs.
	Version string
	// contains filtered or unexported fields
}

GenericLogger is an implementation of the Logger interface.

func New

func New() *GenericLogger

New creates a new GenericLogger that implements the Logger interface.

By default, it sets the level of the logger to LEVEL_INFO.

func (GenericLogger) Debug

func (l GenericLogger) Debug(ctx context.Context, msg string)

Debug logs a debug entry.

func (GenericLogger) DebugWithData

func (l GenericLogger) DebugWithData(ctx context.Context, msg string, info map[string]any)

DebugWithData logs a debug entry.

func (GenericLogger) Error

func (l GenericLogger) Error(ctx context.Context, msg string, err error)

Error logs an error entry.

func (GenericLogger) ErrorWithData

func (l GenericLogger) ErrorWithData(ctx context.Context, msg string, err error, info map[string]any)

ErrorWithData logs an error entry.

func (GenericLogger) Fatal

func (l GenericLogger) Fatal(ctx context.Context, msg string, err error)

Fatal logs a fatal entry and it's followed by a os.Exit(1) call

func (GenericLogger) FatalWithData

func (l GenericLogger) FatalWithData(ctx context.Context, msg string, err error, info map[string]any)

FatalWithData logs a fatal entry and it's followed by a os.Exit(1) call

func (GenericLogger) Info

func (l GenericLogger) Info(ctx context.Context, msg string)

Info logs an info entry.

func (GenericLogger) InfoWithData

func (l GenericLogger) InfoWithData(ctx context.Context, msg string, info map[string]any)

InfoWithData logs an info entry.

func (*GenericLogger) SetLevel

func (l *GenericLogger) SetLevel(level Level) error

SetLevel sets the level of the logger.

If the level is not valid, it returns an error of type errors.Error and leaves the level unchanged.

func (GenericLogger) Trace

func (l GenericLogger) Trace(ctx context.Context, msg string)

Trace logs a debug entry.

func (GenericLogger) TraceWithData

func (l GenericLogger) TraceWithData(ctx context.Context, msg string, info map[string]any)

TraceWithData logs a debug entry.

func (GenericLogger) Warn

func (l GenericLogger) Warn(ctx context.Context, msg string, err error)

Warn logs a warn entry.

func (GenericLogger) WarnWithData

func (l GenericLogger) WarnWithData(ctx context.Context, msg string, err error, info map[string]any)

WarnWithData logs a warn entry.

type Level

type Level int

Level is the level of the logger.

const (
	// LEVEL_TRACE is the trace level.
	LEVEL_TRACE Level = (iota + 1) * 10
	// LEVEL_DEBUG is the debug level.
	LEVEL_DEBUG
	// LEVEL_INFO is the info level.
	LEVEL_INFO
	// LEVEL_WARN is the warn level.
	LEVEL_WARN
	// LEVEL_ERROR is the error level.
	LEVEL_ERROR
	// LEVEL_FATAL is the fatal level.
	LEVEL_FATAL
)

func NewLevelFromString

func NewLevelFromString(s string) (Level, error)

NewLevelFromString returns a level from a string. If the string is not a valid level, an error of type *errors.Error is returned.

func (Level) IsValid

func (l Level) IsValid() bool

IsValid checks if the value is a valid level.

func (Level) String

func (l Level) String() string

String returns the string representation of the level in lower case.

type Logger

type Logger interface {
	// Trace logs a message with the LEVEL_TRACE level.
	Trace(ctx context.Context, msg string)

	// TraceWithData logs a message with the LEVEL_TRACE level
	// and the given data.
	TraceWithData(ctx context.Context, msg string, data map[string]any)

	// Debug logs a message with the LEVEL_DEBUG level.
	Debug(ctx context.Context, msg string)

	// DebugWithData logs a message with the LEVEL_DEBUG level
	// and the given data.
	DebugWithData(ctx context.Context, msg string, data map[string]any)

	// Info logs a message with the LEVEL_INFO level.
	Info(ctx context.Context, msg string)

	// InfoWithData logs a message with the LEVEL_INFO level
	// and the given data.
	InfoWithData(ctx context.Context, msg string, data map[string]any)

	// Warn logs a message with the LEVEL_WARN level.
	Warn(ctx context.Context, msg string, err error)

	// WarnWithData logs a message with the LEVEL_WARN level
	// and the given data.
	WarnWithData(ctx context.Context, msg string, err error, data map[string]any)

	// Error logs a message with the LEVEL_ERROR level.
	Error(ctx context.Context, msg string, err error)

	// ErrorWithData logs a message with the LEVEL_ERROR level
	// and the given data.
	ErrorWithData(ctx context.Context, msg string, err error, data map[string]any)

	// Fatal logs a message with the LEVEL_FATAL level and it's followed by a
	// call to os.Exit(1).
	Fatal(ctx context.Context, msg string, err error)

	// FatalWithData logs a message with the LEVEL_FATAL level
	// and the given data and it's followed by a call to os.Exit(1).
	FatalWithData(ctx context.Context, msg string, err error, data map[string]any)
}

func NewMock

func NewMock() Logger

NewMock creates a new mock logger that implements the Logger interface but does nothing.