logs

README

logs

全新的 v4 版本，对所有功能进行了重构，与之前的几个版本完全不同。 新版本不再追求与标准库的绝对兼容，仅提供了 StdLogger 用于转换成标准库对象的方法。

import "github.com/issue9/logs/v4"

l := logs.New(nil)
l.Debug("debug start...")
l.Debugf("%v start...", "debug")
l.DEBUG().Print("debug start...")

安装

go get github.com/issue9/logs/v4

版权

本项目采用 MIT 开源授权许可证，完整的授权说明可在 LICENSE 文件中找到。

Documentation

Overview

Package logs 日志系统

Index

• func Caller(l *Logs)
• func Created(l *Logs)
• type Entry
  • func (e *Entry) Error(err error)
  • func (e *Entry) Location(depth int) *Entry
  • func (e *Entry) Logs() *Logs
  • func (e *Entry) Print(v ...interface{})
  • func (e *Entry) Printf(format string, v ...interface{})
  • func (e *Entry) Value(name string, val interface{}) Logger
• type Level
  • func ParseLevel(s string) (Level, error)
  • func (l Level) MarshalText() ([]byte, error)
  • func (l Level) String() string
  • func (l *Level) UnmarshalText(data []byte) error
• type Logger
• type Logs
  • func New(w Writer, o ...Option) *Logs
  • func (logs *Logs) DEBUG() Logger
  • func (logs *Logs) Debug(v ...interface{})
  • func (logs *Logs) Debugf(format string, v ...interface{})
  • func (logs *Logs) ERROR() Logger
  • func (logs *Logs) Enable(level ...Level)
  • func (logs *Logs) Error(v ...interface{})
  • func (logs *Logs) Errorf(format string, v ...interface{})
  • func (logs *Logs) FATAL() Logger
  • func (logs *Logs) Fatal(v ...interface{})
  • func (logs *Logs) Fatalf(format string, v ...interface{})
  • func (logs *Logs) HasCaller() bool
  • func (logs *Logs) HasCreated() bool
  • func (logs *Logs) INFO() Logger
  • func (logs *Logs) Info(v ...interface{})
  • func (logs *Logs) Infof(format string, v ...interface{})
  • func (logs *Logs) IsEnable(l Level) bool
  • func (logs *Logs) NewEntry(lv Level) *Entry
  • func (logs *Logs) Output(e *Entry)
  • func (logs *Logs) SetOutput(w Writer)
  • func (logs *Logs) StdLogger(l Level) *log.Logger
  • func (logs *Logs) TRACE() Logger
  • func (logs *Logs) Trace(v ...interface{})
  • func (logs *Logs) Tracef(format string, v ...interface{})
  • func (logs *Logs) WARN() Logger
  • func (logs *Logs) Warn(v ...interface{})
  • func (logs *Logs) Warnf(format string, v ...interface{})
• type Option
• type Pair
• type Writer
  • func MergeWriter(w ...Writer) Writer
  • func NewDispatchWriter(d map[Level]Writer) Writer
  • func NewJSONWriter(format bool, w ...io.Writer) Writer
  • func NewNopWriter() Writer
  • func NewTermWriter(timeLayout string, fore colors.Color, w io.Writer) Writer
  • func NewTextWriter(timeLayout string, w ...io.Writer) Writer

Functions

func Caller

func Caller(l *Logs)

Caller 是否显示记录的定位信息

func Created

func Created(l *Logs)

Created 是否显示记录的创建时间

Types

type Entry

type Entry struct {
	Level   Level     `json:"level"`
	Created time.Time `json:"created,omitempty"` // 日志的生成时间
	Message string    `json:"message"`

	// 以下表示日志的定位信息
	Path string `json:"path,omitempty"`
	Line int    `json:"line,omitempty"`

	// 额外的数据保存在此，比如由 Logger.Value 添加的数据。
	Params []Pair `json:"params,omitempty"`
	// contains filtered or unexported fields
}

Entry 每一条日志产生的数据

func (*Entry) Error

func (e *Entry) Error(err error)

func (*Entry) Location

func (e *Entry) Location(depth int) *Entry

Location 记录位置信息到 Entry

会同时写入 e.Path 和 e.Line 两个值。

depth 表示调用，1 表示调用 Location 的位置；

如果 Logs.HasCaller 为 false，那么此调用将不产生任何内容。

func (*Entry) Logs

func (e *Entry) Logs() *Logs

func (*Entry) Print

func (e *Entry) Print(v ...interface{})

func (*Entry) Printf

func (e *Entry) Printf(format string, v ...interface{})

func (*Entry) Value

func (e *Entry) Value(name string, val interface{}) Logger

type Level

type Level int8

const (
	LevelInfo Level
	LevelTrace
	LevelDebug
	LevelWarn
	LevelError
	LevelFatal
)

目前支持的日志类型

func ParseLevel

func ParseLevel(s string) (Level, error)

func (Level) MarshalText

func (l Level) MarshalText() ([]byte, error)

func (Level) String

func (l Level) String() string

func (*Level) UnmarshalText

func (l *Level) UnmarshalText(data []byte) error

type Logger

type Logger interface {
	// Value 为日志提供额外的参数
	Value(name string, val interface{}) Logger

	// Error 输出 error 接口数据
	//
	// 这是 Print 的特化版本，在输出 error 时性能上会比直接用 Print(err) 好。
	Error(err error)

	Print(v ...interface{})
	Printf(format string, v ...interface{})
}

type Logs

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

func New

func New(w Writer, o ...Option) *Logs

New 声明 Logs 对象

w 如果为 nil，则表示采用 NewNopWriter。

func (*Logs) DEBUG

func (logs *Logs) DEBUG() Logger

func (*Logs) Debug

func (logs *Logs) Debug(v ...interface{})

func (*Logs) Debugf

func (logs *Logs) Debugf(format string, v ...interface{})

func (*Logs) ERROR

func (logs *Logs) ERROR() Logger

func (*Logs) Enable

func (logs *Logs) Enable(level ...Level)

Enable 允许的日志通道

调用此函数之后，所有不在 level 参数的通道都将被关闭。

func (*Logs) Error

func (logs *Logs) Error(v ...interface{})

func (*Logs) Errorf

func (logs *Logs) Errorf(format string, v ...interface{})

func (*Logs) FATAL

func (logs *Logs) FATAL() Logger

func (*Logs) Fatal

func (logs *Logs) Fatal(v ...interface{})

func (*Logs) Fatalf

func (logs *Logs) Fatalf(format string, v ...interface{})

func (*Logs) HasCaller

func (logs *Logs) HasCaller() bool

HasCaller 是否包含定位信息

func (*Logs) HasCreated

func (logs *Logs) HasCreated() bool

HasCreated 是否包含时间信息

func (*Logs) INFO

func (logs *Logs) INFO() Logger

func (*Logs) Info

func (logs *Logs) Info(v ...interface{})

func (*Logs) Infof

func (logs *Logs) Infof(format string, v ...interface{})

func (*Logs) IsEnable

func (logs *Logs) IsEnable(l Level) bool

func (*Logs) NewEntry

func (logs *Logs) NewEntry(lv Level) *Entry

func (*Logs) Output

func (logs *Logs) Output(e *Entry)

Output 输出 Entry 对象

相对于其它方法，该方法比较自由，可以由 e 决定最终输出到哪儿，内容也由用户定义。

func (*Logs) SetOutput

func (logs *Logs) SetOutput(w Writer)

func (*Logs) StdLogger

func (logs *Logs) StdLogger(l Level) *log.Logger

StdLogger 转换成标准库的 Logger

NOTE: 不要设置 log.Logger 的 Prefix 和 flag，这些配置项 logs 本身有提供。 log.Logger 应该仅作为输出 Entry.Message 内容使用。

func (*Logs) TRACE

func (logs *Logs) TRACE() Logger

func (*Logs) Trace

func (logs *Logs) Trace(v ...interface{})

func (*Logs) Tracef

func (logs *Logs) Tracef(format string, v ...interface{})

func (*Logs) WARN

func (logs *Logs) WARN() Logger

func (*Logs) Warn

func (logs *Logs) Warn(v ...interface{})

func (*Logs) Warnf

func (logs *Logs) Warnf(format string, v ...interface{})

type Option

type Option func(*Logs)

type Pair

type Pair struct {
	K string      `json:"k"`
	V interface{} `json:"v"`
}

type Writer

type Writer interface {
	// WriteEntry 将 Entry 写入日志通道
	//
	// NOTE: 此方法应该保证以换行符结尾。
	WriteEntry(*Entry)
}

Writer 将 Entry 转换成文本并输出的功能

func MergeWriter

func MergeWriter(w ...Writer) Writer

MergeWriter 将多个 Writer 合并成一个 Writer 接口对象

func NewDispatchWriter

func NewDispatchWriter(d map[Level]Writer) Writer

NewDispatchWriter 根据 Level 派发到不同的 Writer 对象

func NewJSONWriter

func NewJSONWriter(format bool, w ...io.Writer) Writer

NewJSONWriter 声明 JSON 格式的输出

format 是否格式化 json，如果为 true，会以 \t 作为缩进；

func NewNopWriter

func NewNopWriter() Writer

NewNopWriter 空的 Writer 接口实现

func NewTermWriter

func NewTermWriter(timeLayout string, fore colors.Color, w io.Writer) Writer

NewTermWriter 带颜色的终端输出通道

timeLayout 表示输出的时间格式，遵守 time.Format 的参数要求，如果为空，则不输出时间信息； fore 表示终端信息的字符颜色，背景始终是默认色； w 表示终端的接口，可以是 os.Stderr 或是 os.Stdout，如果是其它的实现者则会带控制字符一起输出；

func NewTextWriter

func NewTextWriter(timeLayout string, w ...io.Writer) Writer