152 lines
3.9 KiB
Markdown
152 lines
3.9 KiB
Markdown
# starlog
|
||
|
||
`starlog` 是一个面向生产环境的 Go 日志库，兼顾控制台可读性与服务端可观测性。
|
||
|
||
- Go 版本：`1.16+`
|
||
- 核心目标：可读、可控、可扩展、可观测
|
||
|
||
完整使用说明见 [docs/USAGE.md](./docs/USAGE.md)，迁移说明见 [docs/MIGRATION.md](./docs/MIGRATION.md)。
|
||
|
||
## 快速开始
|
||
|
||
```go
|
||
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`）
|
||
|
||
## 核心接口
|
||
|
||
```go
|
||
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 基础上扩展更多运行态词汇
|
||
|
||
```go
|
||
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`（保留兼容，不推荐新代码使用）
|
||
|
||
## 生产初始化示例
|
||
|
||
```go
|
||
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` 主路径。
|