logfmt

README

logfmt - An opinionated logging library in logfmt for Go

How opinionated?

• The only possible output format is logfmt.
• All string values are quoted.
• Label keys are sorted except ts for timestamp and msg for the message are sorted.
• time.Time values are in UTC and formatted using time.RFC3339.

Another strong opinion is that it simply writes to an io.Writer. You get to choose if this writer is buffered, a file, a network connection, a terminal. It's not something the package should worry about.

Usage

package main

import (
	"os"
	"time"

	"github.com/inkel/logfmt"
)

func main() {
	l := logfmt.NewLogger(os.Stdout)

	l.Log("a simple log message without any labels", nil)
	l.Logf("a formatted log %s without any labels", nil, "message")

	l.Log("message with a few labels of different types", logfmt.Labels{
		"foo": "bar",
		"err": os.ErrPermission,
		"now": time.Now(),
	})
}

This will produce an output like the following:

ts=2022-07-13T12:31:41Z msg="a simple log message without any labels"
ts=2022-07-13T12:31:41Z msg="a formatted log message without any labels"
ts=2022-07-13T12:31:41Z msg="message with a few labels of different types" err="permission denied" foo="bar" now=2022-07-13T12:31:41Z

License

MIT. See LICENSE.

Documentation

Overview

logfmt is a small and opinionated logging package.

The only possible output format is logfmt, all string values are quoted, keys are sorted, time.Time values are in UTC and formatted using time.RFC3339.

Example

package main

import (
	"os"

	"github.com/inkel/logfmt"
)

func main() {
	l := logfmt.NewLogger(os.Stdout)

	l.Log("just a string", nil)
	l.Logf("%s %d", nil, "Hello", 2022)

	l.Log("a string with labels", logfmt.Labels{
		"lorem": "ipsum",
		"int":   1234,
	})

}

Output:

ts=1978-07-16T05:55:00Z msg="just a string"
ts=1978-07-16T05:55:00Z msg="Hello 2022"
ts=1978-07-16T05:55:00Z msg="a string with labels" int=1234 lorem="ipsum"

Index

• func Format(v any) string
• type Labels
• type Logger
  • func NewLogger(w io.Writer) *Logger
  • func (l *Logger) Log(msg string, labels Labels) (int, error)
  • func (l *Logger) Logf(format string, labels Labels, v ...any) (int, error)

Examples

• Package

Functions

func Format

func Format(v any) string

Format transform any value into a string in an opinionated way:

• String, error and fmt.Stringer values are quoted.
• Floating values uses the %g Format with a maximum of 6 significant digits.
• time.Time are converted to UTC and use time.RFC3339 Format.
• Integer values use strconv.FormatUint and strconv.FormatInt.
• All other values are formatted as %v and quoted if they have a space.

Types

type Labels

type Labels map[string]any

Labels is a custom type for mapping keys and values.

type Logger

type Logger struct {
	// contains filtered or unexported fields
}

Logger is the basic and only type of logger.

func NewLogger

func NewLogger(w io.Writer) *Logger

NewLogger creates a new Logger.

func (*Logger) Log

func (l *Logger) Log(msg string, labels Labels) (int, error)

Log writes the given msg and labels to w.

func (*Logger) Logf

func (l *Logger) Logf(format string, labels Labels, v ...any) (int, error)

Logf writes a formatted message and labels to w. It is equivalent calling [Log] with a previously formatted string.