starlog

starlog 是一个面向生产环境的 Go 日志库，兼顾控制台可读性与服务端可观测性。

Go 版本：1.16+
核心目标：可读、可控、可扩展、可观测

完整使用说明见 docs/USAGE.md，迁移说明见 docs/MIGRATION.md。

快速开始

package main

import (
	"os"

	"b612.me/starlog"
)

func main() {
	log := starlog.NewStarlog(os.Stdout)
	log.SetName("demo")
	log.SetShowStd(true)
	log.SetColorMode(starlog.ColorModeLevelOnly)

	log.WithField("user_id", 42).Info("login ok")
	log.WithError(os.ErrNotExist).Error("open file failed")
}

核心能力

结构化日志：WithField/WithFields/WithError/WithContext
级别过滤：SetLevel/GetLevel/IsLevelEnabled/ParseLevel
格式化输出：TextFormatter、JSONFormatter、自定义 Formatter
多路输出：Sink、MultiSink、RouteHandler
轮转能力：RotatePolicy、StartRotate*、NewRotate*Sink
关键词预设：ApplyKeywordPreset/MergeKeywordPreset（内置 MobaLite/MobaFull）
高频防爆：去重、采样、限流
脱敏治理：规则式脱敏 + 失败策略
指标可观测：写入错误、异步丢弃、pending、多 sink、轮转状态
生命周期收口：Flush/Sync/Close/Shutdown
并发配置：Config 快照 API（GetConfig/ApplyConfig/UpdateConfig）

核心接口

type Handler interface { Handle(context.Context, *Entry) error }
type Formatter interface { Format(*Entry) ([]byte, error) }
type Sink interface { Write([]byte) error; Close() error }

type RotatePolicy interface {
	ShouldRotate(FileInfo, *Entry) bool
	NextPath(string, time.Time) string
}

// 可选扩展。若实现该接口，框架会优先使用 ArchivePath。
type RotateArchivePathProvider interface {
	ArchivePath(string, time.Time) string
}

NextPath 的语义是“归档文件目标路径”。

关键词预设

内置预设：

KeywordPresetMobaLite：常用关键词高亮（error/true/warn/success 等）
KeywordPresetMobaFull：在 Lite 基础上扩展更多运行态词汇

log := starlog.NewDevelopment(os.Stdout)
log.ApplyKeywordPreset(starlog.KeywordPresetMobaLite) // 覆盖现有关键词配置

// 在预设基础上继续自定义
log.SetKeywordColor("OOM", []starlog.Attr{starlog.FgHiRed, starlog.Bold})

// 可选匹配模式（默认关闭，兼容旧行为）
log.SetKeywordMatchOptions(starlog.KeywordMatchOptions{
	IgnoreCase: true, // 忽略大小写
	WholeWord:  true, // 仅匹配完整单词
})

如需保留已有关键词并叠加预设，使用 MergeKeywordPreset(...)。

轮转入口

推荐主路径：

StartRotatePolicy
StartManagedRotatePolicy
StartRotateByTime/StartRotateBySize/StartRotateByTimeSize
StartManagedRotateByTime/StartManagedRotateBySize/StartManagedRotateByTimeSize

RouteHandler 分流文件可直接使用轮转 sink：

NewRotatePolicySink
NewManagedRotatePolicySink
NewRotateBy*Sink
NewManagedRotateBy*Sink

兼容入口：

StartArchive（保留兼容，不推荐新代码使用）

生产初始化示例

package main

import (
	"context"
	"time"

	"b612.me/starlog"
)

func main() {
	log := starlog.NewProduction(nil)
	log.SetName("svc")
	log.SetAutoAppendNewline(true)

	if err := starlog.SetLogFile("./logs/app.log", log, true); err != nil {
		panic(err)
	}

	if err := starlog.StartManagedRotateBySize(log, 200*1024*1024, 5, starlog.RotateManageOptions{
		MaxBackups: 14,
		MaxAge:     14 * 24 * time.Hour,
		Compress:   true,
		Pattern:    "20060102-150405",
	}); err != nil {
		panic(err)
	}

	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
	defer cancel()
	defer log.Shutdown(ctx)

	log.WithField("module", "boot").Info("service started")
}

兼容策略

现有旧 API 仍可继续使用。
新功能优先通过新增 API 提供，不强制破坏式迁移。
新项目建议优先使用 Config API 与 RotatePolicy 主路径。

3.9 KiB Raw Permalink Blame History Unescape Escape