logs

README

Golang logging library

Features:

• Create logs (with timestamp, level, message, location in source code and optional data)
• Serialize structured logs (as JSON, single-line text)
• Write logs to io.Writer easily (including to multiple writers, ex: terminal + file)
• Use common log levels (info, warning, error, etc.)

Todo:

• Add unit tests
• Add example to readme

Documentation

Overview

Package logs provides utilities for handling application logs.

Index

• Constants
• func AsJSON(l *Log) []byte
• func AsPlainText(l *Log) []byte
• func AsPrettyJSON(l *Log) []byte
• type DefaultLogger
  • func (dl *DefaultLogger) LoggerFunc() (LoggerFunc, error)
• type Log
  • func NewLog(msg string, opts ...LogOption) *Log
• type LogLevel
  • func (lvl LogLevel) String() string
• type LogOption
  • func WithData(key string, value any) LogOption
  • func WithFSys(fsys fs.FS) LogOption
  • func WithLevel(lvl string) LogOption
  • func WithSrc() LogOption
  • func WithTimestamp() LogOption
• type LoggerFunc
• type Serializer

Constants

const (
	DataKeyTimestamp   = dataKeyPrefix + "created_at"
	DataKeyLevel       = dataKeyPrefix + "level"
	DataKeySrcFunction = dataKeyPrefix + "src_function"
	DataKeySrcFileLine = dataKeyPrefix + "src_file_line"
	DataKeyFSys        = dataKeyPrefix + "fsys"
)

Functions

func AsJSON

func AsJSON(l *Log) []byte

Returns a single-line-JSON representation of a log. This function will panic if the JSON marshalling of the log returns an error.

func AsPlainText

func AsPlainText(l *Log) []byte

Returns a single-line textual representation of a log.

func AsPrettyJSON

func AsPrettyJSON(l *Log) []byte

Returns the JSON representation of a log with line breaks and indentations. This function will panic if the JSON marshalling of the log returns an error.

Types

type DefaultLogger

type DefaultLogger struct {
	Writers     []io.Writer // For ex: stdout and/or file
	Serializer  Serializer  // For ex: As JSON
	BaseOptions []LogOption // For ex: creation timestamp, source code location
	LogPrefix   string      // For ex: "HTTP" or "Server Name"
	LogSuffix   string      // For ex: ",\n" to seperate JSON logs by commas and line breaks
}

func (*DefaultLogger) LoggerFunc

func (dl *DefaultLogger) LoggerFunc() (LoggerFunc, error)

type Log

type Log struct {
	Message string         `json:"message"`
	Data    map[string]any `json:"data,omitempty"`
}

Log holds logging data, it has a timestamp, a level of severity and a message. It can also include additional data fields.

func NewLog

func NewLog(msg string, opts ...LogOption) *Log

Creates a new log with the timestamp set to the current time.

type LogLevel

type LogLevel int

LogLevel represents the severity of a log. Severity of logs could range anywhere between simple debug info to critical errors.

const (
	LevelUnknown LogLevel = iota // Only for temporary use, like context.TODO()
	LevelDebug                   // Debug (usually not meant to be kept in production)
	LevelInfo                    // Informative data
	LevelWarn                    // Warnings
	LevelError                   // Internal errors
	LevelPanic                   // Panics / fatal errors
)

Represents the level of severity of a log.

func (LogLevel) String

func (lvl LogLevel) String() string

String returns the textual representation of a level.

type LogOption

type LogOption func(*Log)

LogOption modifies a log. LogOptions are typically used to add more data to a log.

func WithData

func WithData(key string, value any) LogOption

WithData adds more data to a log. The value should serializable in order to be writable to the logger output.

func WithFSys

func WithFSys(fsys fs.FS) LogOption

WithFS adds info about a file system (name and size of files) to the log.

func WithLevel

func WithLevel(lvl string) LogOption

WithLevel adds a severity level to the log.

func WithSrc

func WithSrc() LogOption

WithSrc stores the location where the log was created in the source code.

func WithTimestamp

func WithTimestamp() LogOption

WithTimestamp adds a creation datetime to the log.

type LoggerFunc

type LoggerFunc func(*Log) error

type Serializer

type Serializer func(*Log) []byte

Serializer can convert a Log to bytes so that it can be written.