ulog

package module
v1.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 12, 2021 License: MIT Imports: 10 Imported by: 4

README

ulog

ulog is the antidote to modern loggers.

  • ULog only logs JSON formatted output. Structured logging is the only good logging.
  • ULog does not have log levels. If you don't want something logged, don't log it.
  • ULog supports setting fields in context. This is useful for building a log context over the course of an operation.
  • ULog has no dependencies. Using ulog only brings in what it needs, and that isn't much!
  • ULog always uses RFC3339 formatted UTC timestamps, for sanity.

Basic Usage

    ulog.Print("a message")
{ "ts": "2019-11-18T14:00:32Z", "msg": "a message" }

With Fields

    ulog.Print("a message",
        "field", "value",
        "a_number", 123,
        "a_bool", false,
    )
{ "ts": "2019-11-18T14:00:32Z", "msg": "a message", "field": "value", "a_number": 123, "a_bool": false }

With Context

    logger := ulog.With(
        "request_id", "12345",
        "user_id": "big_jim_mcdonald",
    )

    logger.Print("a message",
        "field", "value",
        "a_number", 123,
        "a_bool", false)
{ "ts": "2019-11-18T14:00:32Z", "msg": "a message", "request_id": "12345", "user_id": "big_jim_mcdonald", "field": "value", "a_number": 123, "a_bool": false }

With More Complex Data Types

    ulog.Print("something complex!",
        "array", []string{"this", "is", "an", "array"},
        "map", map[string]string{
            "key": "value",
            "just": "like that",
        },
        "the_ulog_struct_itself", ulog.With("hello", "world"),
    )
{ "ts": "2019-11-18T13:41:56Z", "msg": "something complex!", "array": [ "this", "is", "an", "array" ], "map": { "key": "value", "just": "like that" }, "the_ulog_struct_itself": { "Fields": [ "hello", "world" ] } }

Output To Somewhere Other Than STDOUT

    var sb strings.Builder
    logger := ulog.WithWriter(sb)

    logger.Print("a message",
        "field", "value",
        "a_number", 123,
        "a_bool", false)

    fmt.Println(sb.String())
{ "ts": "2019-11-18T14:00:32Z", "msg": "a message", "field": "value", "a_number": 123, "a_bool": false }
Output to systemd-journald
import "github.com/UNO-SOFT/ulog/ulogjournal"

logger := ulog.WithWriter(ulogjournal.Maybe(os.Stderr))

This will log to /var/run/systemd/journal/socket if exists and os.Stderr is the same as file as $JOURNAL_STREAM says, os.Stderr otherwise.

For more information, see journald and JOURNAL_STREAM.

Documentation

Overview

Package ulog is the antidote to modern loggers.

ulog only logs JSON formatted output. Structured logging is the only good logging.

ulog does not have log levels. If you don't want something logged, don't log it.

ulog does support setting fields in context. Useful for building a log context over the course of an operation.

Index

Constants

View Source
const (
	DefaultTimestampKey = "ts"
	DefaultMessageKey   = "msg"
)

Variables

View Source
var (
	DefaultWriter = os.Stderr
)

Functions

func Log

func Log(keyvals ...interface{}) error

Log is the same as go-kit/kit/log.Log.

func Print added in v1.4.0

func Print(msg string, fields ...Field) error

Print a message using the standard ULog instance

func WithContext added in v1.1.6

func WithContext(ctx context.Context) context.Context

WithContext returns a Context, storing the default ULog in it.

func Write

func Write(msg string, fields ...Field)

Write is the deprecated alias of Print

Types

type Field

type Field interface{}

Field type for all inputs

type ULog

type ULog struct {
	Writer                   io.Writer
	TimestampKey, MessageKey string `json:"-"`
	// contains filtered or unexported fields
}

ULog is the antidote to modern loggers

func FromContext added in v1.1.6

func FromContext(ctx context.Context) ULog

FromContext returns the ULog from the Context, or a disabled logger if no logger is set on the Context.

func New

func New() ULog

New instance of ULog

func NewTestLogger added in v1.2.1

func NewTestLogger(t testLogger) ULog

func With

func With(fields ...Field) ULog

With returns a copy of the standard ULog instance configured with the provided fields

func WithKeyNames

func WithKeyNames(timestampKey, messageKey string) ULog

WithKeyNames returns a copy of the ULog instance with the provided key names for timestamp and message keys.

func WithWriter

func WithWriter(w io.Writer) ULog

WithWriter returns a copy of the standard ULog instance configured to write to the given writer

If w has a Print(string, ...Field) method, then that will be used, without JSON encoding! This can be useful for example with ulogjournal.

func (ULog) Log

func (u ULog) Log(keyvals ...interface{}) error

Log makes ULog implement github.com/go-kit/kit/log.Logger.

func (ULog) Print added in v1.4.0

func (u ULog) Print(msg string, fields ...Field) error

Print a JSON message to the configured writer or os.Stderr.

Includes the message with the key `msg`. Includes the timestamp with the key `ts`. The timestamp field is always first and the message second.

Fields in context will not be overridden. ULog will log the same key multiple times if it is set multiple times. If you don't want that, don't specify it multiple times.

If the underlying Writer has a Print method (with the same signature), than that will be used.

func (ULog) With

func (u ULog) With(fields ...Field) ULog

With returns a copy of the ULog instance with the provided fields preset for every subsequent call.

func (ULog) WithContext added in v1.1.6

func (u ULog) WithContext(ctx context.Context) context.Context

WithContext returns a Context, storing the ULog in int.

func (ULog) WithKeyNames

func (u ULog) WithKeyNames(timestampKey, messageKey string) ULog

WithKeyNames returns a copy of the ULog instance with the provided key names for timestamp and message keys.

func (ULog) Write

func (u ULog) Write(msg string, fields ...Field)

Write is the deprecated alias of Print.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL