log

package module
v2.0.0-beta.4 Latest Latest
Warning

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

 Go to latest Published: Aug 26, 2020 License: MIT Imports: 9 Imported by: 23

README

log GoDoc Build Coverage Status GoReport

It is a simple structured logging package for Go.

Features

  • fast, easy to use, and pretty logging for development
  • low to zero allocation
  • JSON encoding format
  • support multiple output and each output can have their own output level
  • colored text for console handler (linux, mac, and windows are supported)
  • context.Context integration

Handlers

  • console
  • gelf (graylog)
  • memory (unit test)
  • discard (benchmark)

Installation

Use go get

go get -u github.com/jasonsoft/log/v2

Get Started

package main

import (
	"errors"

	"github.com/jasonsoft/log"
	"github.com/jasonsoft/log/handlers/console"
)

func main() {
	// use console handler to log all level logs
	clog := console.New()
	log.AddHandler(clog, log.AllLevels...)

	// print message use DEBUG level
	logger.Debug("hello world")
}

Example

package main

import (
	"errors"

	"github.com/jasonsoft/log"
	"github.com/jasonsoft/log/handlers/console"
)

func main() {
	// use console handler to log all level logs
	clog := console.New()
	log.AddHandler(clog, log.AllLevels...)

	// optional: allow handlers to clear all buffer
	defer log.Flush()

	// use trace to get how long it takes
	defer log.Trace("time to run").Stop()

	logger := log.
		Str("app_id", "santa").
		Str("env", "dev")

	// print message use DEBUG level
	logger.Debug("hello world")

	// log information with custom fileds
	logger.Str("city", "keelung").Info("more info")

	// log error struct and print error message, stack trace will also be recorded
	err := errors.New("something bad happened")
	logger.Err(err).Error("oops...")
}

Output

Field Types

Standard Types
  • Str
  • Bool
  • Int, Int8, Int16, Int32, Int64
  • Uint, Uint8, Uint16, Uint32, Uint64
  • Float32, Float64

Benchmarks

Run on MacBook Pro 15-inch 2018 using go version go1.14.2 windows 10 OS

Using Uber's zap comparison benchmark:

Log a static string, without any context or printf-style templating:

Library Time Bytes Allocated Objects Allocated
jasonsoft log 134 ns/op 0 B/op 0 allocs/op
zerolog 82 ns/op 0 B/op 0 allocs/op
⚡ zap 101 ns/op 0 B/op 0 allocs/op
standard library 339 ns/op 80 B/op 2 allocs/op
⚡ zap (sugared) 187 ns/op 80 B/op 2 allocs/op
go-kit 349 ns/op 640 B/op 11 allocs/op
logrus 3217 ns/op 1195 B/op 24 allocs/op
apex/log 1766 ns/op 344 B/op 6 allocs/op
log15 5157 ns/op 1195 B/op 24 allocs/op

Log a message with a logger that already has 10 fields of context:

Library Time Bytes Allocated Objects Allocated
jasonsoft log 469 ns/op 0 B/op 0 allocs/op
zerolog 78 ns/op 0 B/op 0 allocs/op
⚡ zap 101 ns/op 0 B/op 0 allocs/op
⚡ zap (sugared) 168 ns/op 80 B/op 2 allocs/op
go-kit 5979 ns/op 3793 B/op 58 allocs/op
logrus 25518 ns/op 4186 B/op 68 allocs/op
apex/log 23583 ns/op 3406 B/op 55 allocs/op
log15 21155 ns/op 3446 B/op 72 allocs/op

Log a message and 10 fields:

Library Time Bytes Allocated Objects Allocated
jasonsoft log 7439 ns/op 15086 B/op 42 allocs/op
zerolog 3906 ns/op 2614 B/op 32 allocs/op
⚡ zap 966 ns/op 772 B/op 5 allocs/op
⚡ zap (sugared) 1651 ns/op 1570 B/op 11 allocs/op
go-kit 5367 ns/op 3470 B/op 60 allocs/op
logrus 30444 ns/op 5772 B/op 80 allocs/op
apex/log 25479 ns/op 4363 B/op 67 allocs/op
log15 30315 ns/op 6859 B/op 77 allocs/op

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (

	// ErrorHandler is called whenever handler fails to write an event on its
	// output. If not set, an error is printed on the stderr. This handler must
	// be thread safe and non-blocking.
	ErrorHandler func(err error)

	// AutoStaceTrace add stack trace into entry when use `Error`, `Panic`, `Fatal` level.
	// Default: true
	AutoStaceTrace = true
)

Logger is the default instance of the log package

View Source 
var AllLevels = []Level{
	DebugLevel,
	InfoLevel,
	WarnLevel,
	ErrorLevel,
	PanicLevel,
	FatalLevel,
	TraceLevel,
}

AllLevels is an array of all log levels, for easier registering of all levels to a handler

Functions

func AddHandler 

func AddHandler(handler Handler, levels ...Level)

AddHandler adds a new Log Handler and specifies what log levels the handler will be passed log entries for

func AddHook 

func AddHook(hook Hookfunc) error

AddHook adds a new Hook to log entry

func Debug 

func Debug(msg string)

Debug level formatted message

func Debugf 

func Debugf(msg string, v ...interface{})

Debugf level formatted message

func Error 

func Error(msg string)

Error level formatted message

func Errorf 

func Errorf(msg string, v ...interface{})

Errorf level formatted message

func Fatal 

func Fatal(msg string)

Fatal level formatted message, followed by an exit.

func Fatalf 

func Fatalf(msg string, v ...interface{})

Fatalf level formatted message, followed by an exit.

func Flush 

func Flush()

Flush clear all handler's buffer

func Info 

func Info(msg string)

Info level formatted message

func Infof 

func Infof(msg string, v ...interface{})

Infof level formatted message

func Panic 

func Panic(msg string)

Panic level formatted message

func Panicf 

func Panicf(msg string, v ...interface{})

Panicf level formatted message

func RemoveAllHandlers 

func RemoveAllHandlers()

RemoveAllHandlers removes all handlers

func Warn 

func Warn(msg string)

Warn level formatted message

func Warnf 

func Warnf(msg string, v ...interface{})

Warnf level formatted message

Types

type Context 

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

Context use for meta data

func Bool 

func Bool(key string, val bool) Context

Bool add bool field to current context

func Err 

func Err(err error) Context

Err add error field to current context

func Float32 

func Float32(key string, val float32) Context

Float32 add float32 field to current context

func Float64 

func Float64(key string, val float64) Context

Float64 add Float64 field to current context

func FromContext 

func FromContext(ctx context.Context) Context

FromContext return a log context from the standard context

func Int 

func Int(key string, val int) Context

Int add Int field to current context

func Int16 

func Int16(key string, val int16) Context

Int16 add Int16 field to current context

func Int32 

func Int32(key string, val int32) Context

Int32 add Int32 field to current context

func Int64 

func Int64(key string, val int64) Context

Int64 add Int64 field to current context

func Int8 

func Int8(key string, val int8) Context

Int8 add Int8 field to current context

func Str 

func Str(key string, val string) Context

Str add string field to current context

func Uint 

func Uint(key string, val uint) Context

Uint add Uint field to current context

func Uint16 

func Uint16(key string, val uint16) Context

Uint16 add Uint16 field to current context

func Uint32 

func Uint32(key string, val uint32) Context

Uint32 add Uint32 field to current context

func Uint64 

func Uint64(key string, val uint64) Context

Uint64 add Uint64 field to current context

func Uint8 

func Uint8(key string, val uint8) Context

Uint8 add Uint8 field to current context

func (Context) Bool 

func (c Context) Bool(key string, val bool) Context

Bool add bool field to current context

func (Context) Debug 

func (c Context) Debug(msg string)

Debug level formatted message.

func (Context) Debugf 

func (c Context) Debugf(msg string, v ...interface{})

Debugf level formatted message.

func (Context) Err 

func (c Context) Err(err error) Context

Err add error field to current context

func (Context) Error 

func (c Context) Error(msg string)

Error level formatted message

func (Context) Errorf 

func (c Context) Errorf(msg string, v ...interface{})

Errorf level formatted message

func (Context) Fatal 

func (c Context) Fatal(msg string)

Fatal level formatted message

func (Context) Fatalf 

func (c Context) Fatalf(msg string, v ...interface{})

Fatalf level formatted message

func (Context) Float32 

func (c Context) Float32(key string, val float32) Context

Float32 add float32 field to current context

func (Context) Float64 

func (c Context) Float64(key string, val float64) Context

Float64 add Float64 field to current context

func (Context) Info 

func (c Context) Info(msg string)

Info level formatted message.

func (Context) Infof 

func (c Context) Infof(msg string, v ...interface{})

Infof level formatted message.

func (Context) Int 

func (c Context) Int(key string, val int) Context

Int add Int field to current context

func (Context) Int16 

func (c Context) Int16(key string, val int16) Context

Int16 add Int16 field to current context

func (Context) Int32 

func (c Context) Int32(key string, val int32) Context

Int32 add Int32 field to current context

func (Context) Int64 

func (c Context) Int64(key string, val int64) Context

Int64 add Int64 field to current context

func (Context) Int8 

func (c Context) Int8(key string, val int8) Context

Int8 add Int8 field to current context

func (Context) Interface 

func (c Context) Interface(key string, val interface{}) Context

Interface adds the field key with i marshaled using reflection.

func (Context) Ints 

func (c Context) Ints(key string, val []int) Context

Ints add Int field to current context

func (Context) Panic 

func (c Context) Panic(msg string)

Panic level formatted message

func (Context) Panicf 

func (c Context) Panicf(msg string, v ...interface{})

Panicf level formatted message

func (Context) SaveToDefault 

func (c Context) SaveToDefault()

SaveToDefault save the current context to default logger and these context to be printed with every entry

func (Context) StackTrace 

func (c Context) StackTrace() Context

StackTrace adds stack_trace field to the current context

func (Context) Str 

func (c Context) Str(key string, val string) Context

Str add string field to current context

func (Context) Strs 

func (c Context) Strs(key string, val []string) Context

Strs add string field to current context

func (Context) Time 

func (c Context) Time(key string, val time.Time) Context

Time adds Time field to current context

func (Context) Times 

func (c Context) Times(key string, val []time.Time) Context

Times adds Time field to current context

func (Context) Uint 

func (c Context) Uint(key string, val uint) Context

Uint add Uint field to current context

func (Context) Uint16 

func (c Context) Uint16(key string, val uint16) Context

Uint16 add Uint16 field to current context

func (Context) Uint32 

func (c Context) Uint32(key string, val uint32) Context

Uint32 add Uint32 field to current context

func (Context) Uint64 

func (c Context) Uint64(key string, val uint64) Context

Uint64 add Uint64 field to current context

func (Context) Uint8 

func (c Context) Uint8(key string, val uint8) Context

Uint8 add Uint8 field to current context

func (Context) Warn 

func (c Context) Warn(msg string)

Warn level formatted message.

func (Context) Warnf 

func (c Context) Warnf(msg string, v ...interface{})

Warnf level formatted message.

func (Context) WithContext 

func (c Context) WithContext(ctx context.Context) context.Context

WithContext return a new context with a log context value

type Entry 

type Entry struct {
	Level   Level  `json:"level"`
	Message string `json:"message"`
	// contains filtered or unexported fields
}

Entry defines a single log entry

func Trace 

func Trace(msg string) *Entry

Trace returns a new entry with a Stop method to fire off a corresponding completion log, useful with defer.

func (*Entry) Bool 

func (e *Entry) Bool(key string, val bool) *Entry

Bool add bool field to current entry

func (*Entry) Debug 

func (e *Entry) Debug(msg string)

Debug level message.

func (*Entry) Debugf 

func (e *Entry) Debugf(msg string, v ...interface{})

Debugf level message.

func (*Entry) Dur 

func (e *Entry) Dur(key string, d time.Duration) *Entry

Dur adds Duration field to current entry

func (*Entry) Error 

func (e *Entry) Error(msg string)

Error level message.

func (*Entry) Errorf 

func (e *Entry) Errorf(msg string, v ...interface{})

Errorf level message.

func (*Entry) Fatal 

func (e *Entry) Fatal(msg string)

Fatal level message.

func (*Entry) Fatalf 

func (e *Entry) Fatalf(msg string, v ...interface{})

Fatalf level message.

func (*Entry) Float32 

func (e *Entry) Float32(key string, val float32) *Entry

Float32 add Float32 field to current entry

func (*Entry) Float64 

func (e *Entry) Float64(key string, val float64) *Entry

Float64 adds Float64 field to current entry

func (*Entry) Info 

func (e *Entry) Info(msg string)

Info level message.

func (*Entry) Infof 

func (e *Entry) Infof(msg string, v ...interface{})

Infof level message.

func (*Entry) Int 

func (e *Entry) Int(key string, val int) *Entry

Int adds Int field to current entry

func (*Entry) Int16 

func (e *Entry) Int16(key string, val int16) *Entry

Int16 add Int16 field to current entry

func (*Entry) Int32 

func (e *Entry) Int32(key string, val int32) *Entry

Int32 adds Int32 field to current entry

func (*Entry) Int64 

func (e *Entry) Int64(key string, val int64) *Entry

Int64 add Int64 field to current entry

func (*Entry) Int8 

func (e *Entry) Int8(key string, val int8) *Entry

Int8 add Int8 field to current entry

func (*Entry) Interface 

func (e *Entry) Interface(key string, val interface{}) *Entry

Interface adds the field key with i marshaled using reflection.

func (*Entry) Ints 

func (e *Entry) Ints(key string, val []int) *Entry

Ints adds Int field to current entry

func (*Entry) Panic 

func (e *Entry) Panic(msg string)

Panic level message.

func (*Entry) Panicf 

func (e *Entry) Panicf(msg string, v ...interface{})

Panicf level message.

func (*Entry) StackTrace 

func (e *Entry) StackTrace() *Entry

StackTrace adds stack_trace field to the current context

func (*Entry) Stop 

func (e *Entry) Stop()

Stop should be used with Trace, to fire off the completion message. When an `err` is passed the "error" field is set, and the log level is error.

func (*Entry) Str 

func (e *Entry) Str(key string, val string) *Entry

Str add string field to current entry

func (*Entry) Strs 

func (e *Entry) Strs(key string, val []string) *Entry

Strs add string field to current entry

func (*Entry) Time 

func (e *Entry) Time(key string, val time.Time) *Entry

Time adds Time field to current entry

func (*Entry) Times 

func (e *Entry) Times(key string, val []time.Time) *Entry

Times adds Time field to current entry

func (*Entry) Trace 

func (e *Entry) Trace(msg string) *Entry

Trace returns a new entry with a Stop method to fire off a corresponding completion log, useful with defer.

func (*Entry) Uint 

func (e *Entry) Uint(key string, val uint) *Entry

Uint add Uint field to current entry

func (*Entry) Uint16 

func (e *Entry) Uint16(key string, val uint16) *Entry

Uint16 add Uint16 field to current entry

func (*Entry) Uint32 

func (e *Entry) Uint32(key string, val uint32) *Entry

Uint32 add Uint32 field to current entry

func (*Entry) Uint64 

func (e *Entry) Uint64(key string, val uint64) *Entry

Uint64 add Uint64 field to current entry

func (*Entry) Uint8 

func (e *Entry) Uint8(key string, val uint8) *Entry

Uint8 add Uint8 field to current entry

func (*Entry) Warn 

func (e *Entry) Warn(msg string)

Warn level message.

func (*Entry) Warnf 

func (e *Entry) Warnf(msg string, v ...interface{})

Warnf level message.

type Flusher 

type Flusher interface {
	Flush() error
}

Flusher is an interface that allow handles have the ability to clear buffer and close connection

type Handler 

type Handler interface {
	BeforeWriting(*Entry) error
	Write([]byte) error
}

Handler is an interface that log handlers need to be implemented

type Hookfunc 

type Hookfunc func(*Entry) error

Hookfunc is an func that allow us to do something before writing

type Level 

type Level uint8

Level of the log 

const (
	DebugLevel Level = iota
	InfoLevel
	WarnLevel
	ErrorLevel
	PanicLevel
	FatalLevel
	TraceLevel
)

Log levels.

func GetLevelsFromMinLevel 

func GetLevelsFromMinLevel(minLevel string) []Level

GetLevelsFromMinLevel returns Levels array which above minLevel

func (Level) String 

func (p Level) String() string

String returns the string representation of a logging level.

Source Files

View all Source files

Directories

Path Synopsis
examples
error
simple
handlers
console
discard
Package discard implements a no-op handler useful for benchmarks and tests.
 Package discard implements a no-op handler useful for benchmarks and tests.
gelf
memory
Package memory implements an in-memory handler useful for testing, as the entries can be accessed after writes.
 Package memory implements an in-memory handler useful for testing, as the entries can be accessed after writes.
internal
json

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.