Golang最高效低内存占用的JSON日志记录插件库onelog的使用

Onelog是一个非常简单但非常高效的JSON日志记录库。它是目前最快的JSON日志记录器之一，同时也是内存分配最少的日志记录器之一。

安装

go get github.com/francoispqt/onelog

基本使用

import "github.com/francoispqt/onelog"

func main() {
    // 创建一个新的Logger
    // 第一个参数是io.Writer
    // 第二个参数是日志级别，是一个整数
    logger := onelog.New(
        os.Stdout, 
        onelog.ALL, // onelog.DEBUG|onelog.INFO|onelog.WARN|onelog.ERROR|onelog.FATAL的快捷方式
    )
    logger.Info("hello world !") // {"level":"info","message":"hello world"}
}

日志级别

日志级别是映射到字符串的整数。日志记录器将使用高效的位运算检查是否启用了级别，如果禁用，它会立即返回，这使得onelog在运行禁用日志记录时成为最快的，分配为0，操作时间小于1ns/op。

创建日志记录器时，必须使用|运算符设置不同的级别。

可用级别

• onelog.DEBUG
• onelog.INFO
• onelog.WARN
• onelog.ERROR
• onelog.FATAL

logger := onelog.New(
    os.Stdout, 
    onelog.INFO|onelog.WARN,
)

动态设置级别示例

var logger *onelog.Logger

func init() {
    // 如果是调试模式，启用DEBUG级别
    if os.Getenv("DEBUG") != "" {
        logger = onelog.New(
            os.Stdout, 
            onelog.ALL, // onelog.DEBUG|onelog.INFO|onelog.WARN|onelog.ERROR|onelog.FATAL的快捷方式
        )
        return
    }
    logger = onelog.New(
        os.Stdout, 
        onelog.INFO|onelog.WARN|onelog.ERROR|onelog.FATAL,
    )
}

修改级别文本值

onelog.LevelText(onelog.INFO, "INFO")

钩子(Hook)

你可以定义一个钩子，它将在每条日志消息上运行。

logger := onelog.New(
    os.Stdout, 
    onelog.ALL,
)
logger.Hook(func(e onelog.Entry) {
    e.String("time", time.Now().Format(time.RFC3339))
})
logger.Info("hello world !") // {"level":"info","message":"hello world","time":"2018-05-06T02:21:01+08:00"}

上下文(Context)

上下文允许强制使用分组格式，其中来自所有日志记录方法(With、Info、Debug、InfoWith、InfoWithEntry等)的所有日志字段键值对(除了使用logger.Hook的值)将被包含在作为其键提供的给定上下文名称中。

logger := onelog.NewContext(
    os.Stdout, 
    onelog.INFO|onelog.WARN,
    "params"
)

logger.InfoWithFields("breaking news !", func(e onelog.Entry) {
    e.String("userID", "123455")
}) 

// {"level":"info","message":"breaking news !", "params":{"userID":"123456"}}

从父日志记录器继承上下文

parentLogger := onelog.New(
    os.Stdout, 
    onelog.INFO|onelog.WARN,
)

logger := parentLogger.WithContext("params")
logger.InfoWithFields("breaking news !", func(e onelog.Entry) {
    e.String("userID", "123455")
}) 

// {"level":"info","message":"breaking news !", "params":{"userID":"123456"}}

日志记录

无额外字段的日志记录

logger := onelog.New(
    os.Stdout, 
    onelog.ALL,
)
logger.Debug("i'm not sure what's going on") // {"level":"debug","message":"i'm not sure what's going on"}
logger.Info("breaking news !") // {"level":"info","message":"breaking news !"}
logger.Warn("beware !") // {"level":"warn","message":"beware !"}
logger.Error("my printer is on fire") // {"level":"error","message":"my printer is on fire"}
logger.Fatal("oh my...") // {"level":"fatal","message":"oh my..."}

带额外字段的日志记录

logger := onelog.New(
    os.Stdout, 
    onelog.ALL,
)

logger.DebugWithFields("i'm not sure what's going on", func(e onelog.Entry) {
    e.String("string", "foobar")
    e.Int("int", 12345)
    e.Int64("int64", 12345)
    e.Float("float64", 0.15)
    e.Bool("bool", true)
    e.Err("err", errors.New("someError"))
    e.ObjectFunc("user", func(e Entry) {
        e.String("name", "somename")
    })
}) 
// {"level":"debug","message":"i'm not sure what's going on","string":"foobar","int":12345,"int64":12345,"float64":0.15,"bool":true,"err":"someError","user":{"name":"somename"}}

链式语法

logger.InfoWith("foo bar").
    Int("testInt", 1).
    Int64("testInt64", 2).
    Float("testFloat", 1.15234).
    String("testString", "string").
    Bool("testBool", true).
    ObjectFunc("testObj", func(e Entry) {
        e.Int("testInt", 100)
    }).
    Object("testObj2", testObj). // 实现gojay.MarshalerJSONObject
    Array("testArr", testArr). // 实现gojay.MarshalerJSONArray
    Err("testErr", errors.New("my printer is on fire !")).
    Write() // 别忘了调用这个方法!

累积上下文

你可以创建一个带有一些累积上下文的日志记录器，这些上下文将包含在此日志记录器创建的所有日志中。

logger := onelog.New(
    os.Stdout, 
    onelog.ALL,
).With(func(e onelog.Entry) {
    e.String("userID", "123456")
})

logger.Info("user logged in") // {"level":"info","message":"user logged in","userID":"123456"}

logger.Debug("wtf?") // {"level":"debug","message":"wtf?","userID":"123456"}

logger.ErrorWithFields("Oops", func(e onelog.Entry) {
    e.String("error_code", "ROFL")
}) // {"level":"error","message":"oops","userID":"123456","error_code":"ROFL"}

修改全局配置

修改级别文本值

onelog.LevelText(onelog.INFO, "INFO")

修改消息键

onelog.MsgKey("msg")

修改级别键

onelog.LevelKey("lvl")

注意：这些更改是全局的(影响日志记录器的所有实例)。此外，这些函数应该在运行时只调用一次，以避免任何数据竞争问题。

性能基准

Onelog在性能方面表现优异，特别是在禁用日志记录时具有零分配和极低的延迟。以下是部分基准测试结果：

禁用日志记录

带字段的禁用日志记录

记录基本消息

Onelog是一个高效、低内存占用的JSON日志记录解决方案，特别适合性能敏感的应用场景。