logger

README

go-logger

基于 zap 的轻量封装，提供：

• 控制台日志输出（面向人读）
• JSON 日志输出（写入自定义回调，面向机器解析）
• 可选异步写入器（队列满丢弃，避免阻塞业务线程）

安装

go get github.com/fireflycore/go-logger

快速开始

仅控制台输出

package main

import logger "github.com/fireflycore/go-logger"

func main() {
	l := logger.New(&logger.Conf{
		Console: true,
		Remote:  false,
	}, nil)

	l.Info("hello")
}

JSON 输出到回调

当 Remote=true 且提供了 handle 时，会把日志以 JSON bytes 的形式写入回调。

package main

import logger "github.com/fireflycore/go-logger"

func main() {
	l := logger.New(&logger.Conf{
		Console: false,
		Remote:  true,
	}, func(b []byte) {
		_ = b
	})

	l.Info("hello")
}

JSON 输出异步化

如果回调写入较慢，可以用 AsyncLogger 将写入异步化：

package main

import logger "github.com/fireflycore/go-logger"

func main() {
	async := logger.NewAsyncLogger(1024, func(b []byte) {
		_ = b
	})

	l := logger.New(&logger.Conf{
		Console: false,
		Remote:  true,
	}, async.Logger)

	l.Info("hello")
}

配置说明

Conf 支持三个字段：

• Console：是否输出到 stdout（控制台 encoder）
• Remote：是否输出到回调（JSON encoder；需要同时提供 handle 才生效）
• Level：日志等级（debug/info/warn/error/panic；默认 info）

回调输出格式

当 Remote=true 且提供 handle 时，handle 会收到一段 JSON bytes，字段如下：

• Path：调用位置（file:line）
• Level：数字等级（兼容历史格式）
• Content：日志消息
• TraceId：可选字段（当日志 fields 中包含 trace_id 或 TraceId 时输出）
• CreatedAt：时间（time.DateTime 格式）

其中 TraceId 的常见写法：

l.Info("hello", zap.String("trace_id", "xxx"))

Documentation

Index

• func New(conf *Conf, handle func(b []byte)) *zap.Logger
• type AsyncLogger
  • func NewAsyncLogger(size int, handle func(b []byte)) *AsyncLogger
  • func (l *AsyncLogger) Close()
  • func (l *AsyncLogger) Logger(b []byte)
  • func (l *AsyncLogger) Sync() error
  • func (l *AsyncLogger) Write(p []byte) (n int, err error)
• type Conf
  • func (c *Conf) WithHandle(handle func(b []byte))

Functions

func New

func New(conf *Conf, handle func(b []byte)) *zap.Logger

New 构造一个 zap.Logger

- Console=true 时输出到 stdout（面向人读） - Remote=true 且提供 handle 时输出 JSON 到 handle（面向机器解析） - 两者都未启用时返回 Nop logger，避免 nil 引用

Types

type AsyncLogger

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

AsyncLogger 用于把日志写入异步队列，然后由后台 goroutine 调用 handle 消费。

该类型同时实现 io.Writer，可直接作为 zap 的写入目标。

func NewAsyncLogger

func NewAsyncLogger(size int, handle func(b []byte)) *AsyncLogger

NewAsyncLogger 创建一个异步写入器。

size 为队列长度；当队列已满时，新日志会被丢弃（不阻塞调用方）。

func (*AsyncLogger) Close

func (l *AsyncLogger) Close()

func (*AsyncLogger) Logger

func (l *AsyncLogger) Logger(b []byte)

func (*AsyncLogger) Sync

func (l *AsyncLogger) Sync() error

func (*AsyncLogger) Write

func (l *AsyncLogger) Write(p []byte) (n int, err error)

Write 实现 io.Writer。

这里会复制入参切片，避免上层复用/修改同一底层数组导致数据竞争或内容错乱。

type Conf

type Conf struct {
	Console bool   `json:"console"`
	Remote  bool   `json:"remote"`
	Level   string `json:"level"`
	// contains filtered or unexported fields
}

Conf 是 logger 的配置项 - Console：是否启用控制台输出 - Remote：是否启用远端输出（需要同时提供 handle 才会生效）

func (*Conf) WithHandle

func (c *Conf) WithHandle(handle func(b []byte))

WithHandle 设置远端输出回调

handle 会接收到 JSON bytes（字段见 README）