Golang高性能结构化日志记录与动态字段管理插件库xylog的使用

xylog是一个专为Golang设计的高性能结构化日志库，它结合了Python logging的设计理念和Zap的编码方法，提供了层级日志记录、结构化日志、动态字段管理等功能。

快速开始

你可以使用SimpleConfig轻松配置一个日志记录器：

var config = &xylog.SimpleConfig{
    Name:   "simple-logger",
    Level:  xylog.DEBUG,
    Writer: os.Stdout,
}

var logger, err = config.AddMacro("level", "levelname").Apply()
if err != nil {
    fmt.Println("An error occurred:", err)
    os.Exit(1)
}
defer xylog.Flush()

logger.Debug("logging message")
logger.Event("create-user").Field("username", "foo").
    Field("email", "bar@buzz.com").Field("Age", 25).Info()

// Output:
// level=DEBUG messsage="logging message"
// level=INFO event=create-user username=foo email=bar@buzz.com Age=25

完整配置

Logger

Logger是应用程序代码直接使用的日志记录器。Logger名称是点分隔的层次结构名称，如"a"、“a.b”、"a.b.c"等。

var logger = xylog.GetLogger("example")
defer xylog.Flush()

Handler

Handler负责生成日志消息。每个GetHandler调用返回相同的Handler实例。

var handler = xylog.GetHandler("handler")

Emitter

Emitter将日志消息写入指定的输出。目前仅支持StreamEmitter。

var emitter = xylog.NewStreamEmitter(os.Stdout)

组合使用

handler.AddEmitter(emitter)
logger.AddHandler(handler)

日志级别

Logger和Handler都有自己的日志级别。如果日志级别低于设置的级别，消息将不会被记录。

logger.SetLevel(xylog.DEBUG)

logger.Debug("foo")
logger.Warning("bar")

// Output:
// message=foo
// message=bar

结构化日志

使用EventLogger可以记录包含多个字段的结构化日志：

logger.Event("add-user").Field("name", "david").Field("email", "david@dad.com").Info()

// Output:
// event=add-user name=david email=david@dad.com

可以添加永久字段到Logger或Handler：

logger.AddField("host", "localhost")
handler.AddField("port", 3333)

logger.Info("start server")

// Output:
// host=localhost port=3333 message="start server"

支持JSON格式：

import "github.com/xybor-x/xylog/encoding"

handler.SetEncoding(encoding.NewJSONEncoding())

logger.Warning("this is a message")
logger.Event("failed").Field("id", 1).Error()

// Output:
// {"message":"this is a message"}
// {"event":"failed","id": 1}

宏(Macros)

宏是每次记录日志时值都会变化的特殊字段：

handler.AddMacro("level", "levelname")

logger.Warning("this is a warning message")

// Output:
// level=WARNING message="this is a warning message"

过滤器(Filter)

Filter可用于Handler和Logger，提供比级别更复杂的过滤功能：

type NameFilter struct {
    name string
}

func (f *NameFilter) Filter(record xylog.LogRecord) bool {
    return f.name == record.Name
}

handler.AddFilter(&NameFilter{"example.user"})

var userLogger = xylog.GetLogger("example.user")
var serviceLogger = xylog.GetLogger("example.service")

userLogger.Warning("this is the user logger")
serviceLogger.Warning("this is the service logger")

// Output:
// message="this is the user logger"

层级日志记录器

Logger名称是层次结构的，可以在不同的应用区域设置公共Logger：

// common/setup.go
func init() {
    var emitter = xylog.NewStreamEmitter(os.Stderr)
    var handler = xylog.GetHandler("")
    handler.AddEmitter(emitter)
    handler.SetEncoding(encoding.NewJSONEncoding())
    handler.AddMacro("time", "asctime")
    handler.AddMacro("level", "levelname")

    var logger = xylog.GetLogger("parent")
    logger.AddHandler(handler)
    logger.SetLevel(xylog.WARNING)
}

// user/foo.go
import _ "common"

var logger = xylog.GetLogger("parent.user")
defer xylog.Flush()
logger.SetLevel(xylog.INFO)
logger.AddField("module", "user")

logger.Info("this is user module")
logger.Debug("this is a not logged message")

// Output:
// time=[time] level=INFO module=user message="this is user module"

性能基准

xylog在性能方面表现优异，以下是与其他流行日志库的对比：

记录一条消息和10个字段

记录一条带有10个预定义上下文字段的消息

记录静态字符串

xylog提供了丰富的功能和良好的性能表现，是Golang项目中结构化日志记录的一个优秀选择。