golog

README

golog

golog is a multilayer & leveled & structured logger for golang.

Documentation

• API Reference

Installation

Install golog using the "go get" command:

go get github.com/someonegg/golog

The Go distribution is golog's only dependency.

Documentation

Overview

Package golog implements a multilayer & leveled & structured logging API.

A structured log contains a set of fields, a field is a key-value pair. The keys's type is string, the value's type is arbitrary. There are two special rules for value.

If the type is "error", use v.Error()
If the type is "fmt.Stringer", use v.String()

All logs have three special fields: "level", "time", "message".

Log generated by Logger. A logger has three properties: "level", "handler", "predefs".

The "level" controls whether a log will be passed to the handler, the rule is
  "log.level >= logger.level".
The "handler" will process logs, outputting them.
The "predefs" is set of fields, all logs generated by this logger will include them.

You can create sub-loggers from an existing logger, the topmost logger is RootLogger.

Sub-logger will dynamically & recursively inherit properties from its parent logger.

It can set its own "level", "handler". When not setted, use the inherited value.
It can modify (add del) its own "predefs". When log, use (inherited + its own) "predefs".

The simplest way to use golog is:

package main
import (
  "github.com/someonegg/golog"
)
var log = golog.SubLoggerWithFields(golog.RootLogger, "module", "main")
func main() {
    golog.RootLogger.SetHandler(xxx)
    ...
    log.Info("App start", "pid", pid)
    ...
}

Index

• Constants
• Variables
• type Field
• type Fields
• type Handler
  • func NewHandler(w io.Writer) Handler
• type HandlerFunc
  • func (f HandlerFunc) ProcessLog(l *Log)
• type Log
• type Logger
  • func SubLoggerWithFields(parent Logger, kvfields ...interface{}) Logger
  • func SubLoggerWithHandler(parent Logger, handler Handler) Logger
  • func SubLoggerWithLevel(parent Logger, level int) Logger

Constants

const (
	LevelDebug = iota
	LevelInfo
	LevelWarn
	LevelError
	LevelPanic
	LevelFatal
)

Supported log level.

Variables

var LevelName = [...]string{
	LevelDebug: "Debug",
	LevelInfo:  "Info",
	LevelWarn:  "Warn",
	LevelError: "Error",
	LevelPanic: "Panic",
	LevelFatal: "Fatal",
}

Types

type Field

type Field struct {
	K string
	V interface{}
}

Field represents a log field.

type Fields

type Fields map[string]interface{}

Fields is map type of field-key to field-value.

type Handler

type Handler interface {
	ProcessLog(l *Log)
}

Handler is used to process logs, outputting them to stdio, file or remote services.

Implementations must not retain log, but can modify it temporarily.

Multiple goroutines may invoke methods on a Handler simultaneously.

func NewHandler

func NewHandler(w io.Writer) Handler

NewHandler create a handler outputting to w. The handler is a development-friendly textual handler.

type HandlerFunc

type HandlerFunc func(l *Log) error

The HandlerFunc type is an adapter to allow the use of ordinary functions as log handlers. If f is a function with the appropriate signature, HandlerFunc(f) is a Handler object that calls f.

func (HandlerFunc) ProcessLog

func (f HandlerFunc) ProcessLog(l *Log)

type Log

type Log struct {
	Level   int
	Time    time.Time
	Message string
	Fields  Fields // not nil
}

Log represents a single structured log.

type Logger

type Logger interface {
	// Create a sub logger from this logger.
	SubLogger() Logger

	// Level property. It controls whether a log will be
	// passed to the handler, the rule is:
	//   [log.level >= logger.level]
	//
	// When not setted, use the inherited value.
	//
	Level() int
	SetLevel(level int)
	UnsetLevel()

	// Handler property. The log will be passed to it.
	//
	// When nil,logs will be discarded.
	// When not setted, use the inherited value.
	//
	Handler() Handler
	SetHandler(handler Handler)
	UnsetHandler()

	// Predefs property. All logs generated by this logger will include them.
	//
	// Called when log, returns (inherited + its own) "predefs".
	//   [pick its own when repeated in merging]
	Predefs() Fields
	AddPredef(key string, val interface{})
	DelPredef(key string)

	// Log operation.
	//
	Debug(message string, kvfields ...interface{})
	Info(message string, kvfields ...interface{})
	Warn(message string, kvfields ...interface{})
	Error(message string, kvfields ...interface{})
	// Log followed by a call to panic(message).
	Panic(message string, kvfields ...interface{})
	// Log followed by a call to os.Exit(1).
	Fatal(message string, kvfields ...interface{})
}

Logger is the logger interface.

var RootLogger Logger = &logger{
	level:         LevelDebug,
	levelSetted:   true,
	handler:       NewHandler(os.Stderr),
	handlerSetted: true,
}

The root logger, its level is debug, its handler is NewHandler(os.Stderr).

func SubLoggerWithFields

func SubLoggerWithFields(parent Logger, kvfields ...interface{}) Logger

SubLogger followed by AddPredef... .

func SubLoggerWithHandler

func SubLoggerWithHandler(parent Logger, handler Handler) Logger

SubLogger followed by SetHandler .

func SubLoggerWithLevel

func SubLoggerWithLevel(parent Logger, level int) Logger

SubLogger followed by SetLevel .