# 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` 主路径。