golang-samber-slog by samber/cc-skills-golang
npx skills add https://github.com/samber/cc-skills-golang --skill golang-samber-slog角色: 你是一名 Go 日志架构师。你设计的日志流水线让每条记录都流经正确的处理器——采样器在早期丢弃噪音,格式化器在记录离开进程前剥离 PII(个人身份信息),路由器将错误发送到 Sentry,而信息则发送到 Loki。
适用于 Go 1.21+ 的 20 多个可组合的 slog.Handler 包。包含三个核心流水线库,以及 HTTP 中间件和后端接收器,它们都实现了标准的 slog.Handler 接口。
官方资源:
此技能并非详尽无遗。更多信息请参考库文档和代码示例。Context7 可以作为一个发现平台提供帮助。
每个 samber/slog 流水线都遵循一个规范的顺序。记录从左向右流动——将采样放在首位以尽早丢弃,避免在永远不会到达接收器的记录上浪费 CPU。
record → [Sampling] → [Pipe: trace/PII] → [Router] → [Sinks]
顺序很重要:在格式化之前采样可以节省 CPU。在路由之前格式化确保所有接收器都接收到干净的属性。颠倒顺序会对最终被丢弃的记录做无用功。
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| 库 |
|---|
| 用途 |
|---|
| 关键构造函数 |
|---|
slog-multi | 处理器组合 | Fanout, Router, FirstMatch, Failover, Pool, Pipe |
slog-sampling | 吞吐量控制 | UniformSamplingOption, ThresholdSamplingOption, AbsoluteSamplingOption, CustomSamplingOption |
slog-formatter | 属性转换 | PIIFormatter, ErrorFormatter, FormatByType[T], FormatByKey, FlattenFormatterMiddleware |
六种组合模式,分别对应不同的路由需求:
| 模式 | 行为 | 延迟影响 |
|---|---|---|
Fanout(handlers...) | 顺序广播到所有处理器 | 所有处理器延迟之和 |
Router().Add(h, predicate).Handler() | 路由到所有匹配的处理器 | 匹配处理器延迟之和 |
Router().Add(...).FirstMatch().Handler() | 仅路由到第一个匹配项 | 单个处理器延迟 |
Failover()(handlers...) | 顺序尝试直到一个成功 | 主处理器延迟(理想情况) |
Pool()(handlers...) | 并发广播到所有处理器 | 所有处理器延迟的最大值 |
Pipe(middlewares...).Handler(sink) | 接收器前的中间件链 | 中间件开销 + 接收器延迟 |
// 将错误路由到 Sentry,所有日志路由到 stdout
logger := slog.New(
slogmulti.Router().
Add(sentryHandler, slogmulti.LevelIs(slog.LevelError)).
Add(slog.NewJSONHandler(os.Stdout, nil)).
Handler(),
)
内置谓词:LevelIs, LevelIsNot, MessageIs, MessageIsNot, MessageContains, MessageNotContains, AttrValueIs, AttrKindIs。
关于每种模式的完整代码示例,请参阅 流水线模式。
| 策略 | 行为 | 最适合 |
|---|---|---|
| Uniform | 丢弃固定百分比的所有记录 | 开发/预发布环境降噪 |
| Threshold | 每个时间间隔记录前 N 条,然后以速率 R 采样 | 生产环境——保持初始可见性 |
| Absolute | 全局限制每个时间间隔 N 条记录 | 严格的成本控制 |
| Custom | 用户函数为每条记录返回采样率 | 基于级别或时间的规则 |
采样器必须是流水线中最外层的处理器——将其放在格式化之后会浪费 CPU 来处理最终被丢弃的记录。
// Threshold:每 5 秒记录前 10 条,然后采样 10% —— 错误始终通过 Router 传递
logger := slog.New(
slogmulti.
Pipe(slogsampling.ThresholdSamplingOption{
Tick: 5 * time.Second, Threshold: 10, Rate: 0.1,
}.NewMiddleware()).
Handler(innerHandler),
)
匹配器对相似记录进行分组以去重:MatchByLevel(), MatchByMessage(), MatchByLevelAndMessage()(默认), MatchBySource(), MatchByAttribute(groups, key)。
关于策略比较和配置详情,请参阅 采样策略。
作为 Pipe 中间件应用,以便所有下游处理器都接收到干净的属性。
logger := slog.New(
slogmulti.Pipe(slogformatter.NewFormatterMiddleware(
slogformatter.PIIFormatter("user"), // 掩码 PII 字段
slogformatter.ErrorFormatter("error"), // 结构化错误信息
slogformatter.IPAddressFormatter("client"), // 掩码 IP 地址
)).Handler(slog.NewJSONHandler(os.Stdout, nil)),
)
关键格式化器:PIIFormatter, ErrorFormatter, TimeFormatter, UnixTimestampFormatter, IPAddressFormatter, HTTPRequestFormatter, HTTPResponseFormatter。通用格式化器:FormatByType[T], FormatByKey, FormatByKind, FormatByGroup, FormatByGroupKey。使用 FlattenFormatterMiddleware 展平嵌套属性。
跨框架的一致模式:router.Use(slogXXX.New(logger))。
可用包:slog-gin, slog-echo, slog-fiber, slog-chi, slog-http (net/http)。
所有包共享一个 Config 结构体,包含:DefaultLevel, ClientErrorLevel, ServerErrorLevel, WithRequestBody, WithResponseBody, WithUserAgent, WithRequestID, WithTraceID, WithSpanID, Filters。
// Gin 带过滤器 —— 跳过健康检查
router.Use(sloggin.NewWithConfig(logger, sloggin.Config{
DefaultLevel: slog.LevelInfo,
ClientErrorLevel: slog.LevelWarn,
ServerErrorLevel: slog.LevelError,
WithRequestBody: true,
Filters: []sloggin.Filter{
sloggin.IgnorePath("/health", "/metrics"),
},
}))
关于特定框架的设置,请参阅 HTTP 中间件。
所有都遵循 Option{}.NewXxxHandler() 构造函数模式。
| 类别 | 包 |
|---|---|
| 云服务 | slog-datadog, slog-sentry, slog-loki, slog-graylog |
| 消息队列 | slog-kafka, slog-fluentd, slog-logstash, slog-nats |
| 通知 | slog-slack, slog-telegram, slog-webhook |
| 存储 | slog-parquet |
| 桥接 | slog-zap, slog-zerolog, slog-logrus |
批处理处理器需要优雅关闭 —— slog-datadog, slog-loki, slog-kafka 和 slog-parquet 在内部缓冲记录。关闭时刷新(例如,Datadog 的 handler.Stop(ctx),Loki 的 lokiClient.Stop(),Kafka 的 writer.Close()),否则缓冲的日志会丢失。
关于配置示例和关闭模式,请参阅 后端处理器。
| 错误 | 失败原因 | 修复方法 |
|---|---|---|
| 在格式化之后采样 | 浪费 CPU 格式化最终被丢弃的记录 | 将采样器作为最外层处理器 |
| 扇出到多个同步处理器 | 阻塞调用者——延迟是所有处理器之和 | 使用 Pool() 进行并发分发 |
| 批处理处理器缺少关闭刷新 | 关闭时缓冲的日志丢失 | defer handler.Stop(ctx) (Datadog), defer lokiClient.Stop() (Loki), defer writer.Close() (Kafka) |
| 路由器没有默认/兜底处理器 | 未匹配的记录被静默丢弃 | 添加一个没有谓词的处理器作为兜底 |
AttrFromContext 没有 HTTP 中间件 | 上下文没有要提取的请求属性 | 先安装 slog-gin/echo/fiber/chi 中间件 |
使用没有中间件的 Pipe | 无操作包装器增加了每条记录的开销 | 如果不需要中间件,移除 Pipe() |
Pool() 将其减少到 max(latencies)slog.LogValuergo test -bench 对你的流水线进行基准测试诊断: 测量你的流水线每条记录的内存分配和延迟,并确定链中哪个处理器分配最多。
slogmulti.NewHandleInlineHandler 测试流水线 —— 断言记录到达每个阶段,无需真实接收器AttrFromContext 将请求范围的属性从 HTTP 中间件传播到所有处理器samber/cc-skills-golang@golang-observability 技能以了解 slog 基础(级别、上下文、处理器设置、迁移)samber/cc-skills-golang@golang-error-handling 技能以了解日志或返回规则samber/cc-skills-golang@golang-security 技能以了解日志中的 PII 处理samber/cc-skills-golang@golang-samber-oops 技能以了解使用 samber/oops 的结构化错误上下文如果你在任何 samber/slog-* 包中遇到错误或意外行为,请在相关仓库提交问题(例如,slog-multi/issues, slog-sampling/issues)。
每周安装次数
69
仓库
GitHub 星标数
184
首次出现
3 天前
安全审计
安装于
opencode67
codex66
gemini-cli66
github-copilot65
kimi-cli65
amp65
Persona: You are a Go logging architect. You design log pipelines where every record flows through the right handlers — sampling drops noise early, formatters strip PII before records leave the process, and routers send errors to Sentry while info goes to Loki.
20+ composable slog.Handler packages for Go 1.21+. Three core pipeline libraries plus HTTP middlewares and backend sinks that all implement the standard slog.Handler interface.
Official resources:
This skill is not exhaustive. Please refer to library documentation and code examples for more informations. Context7 can help as a discoverability platform.
Every samber/slog pipeline follows a canonical ordering. Records flow left to right — place sampling first to drop early and avoid wasting CPU on records that never reach a sink.
record → [Sampling] → [Pipe: trace/PII] → [Router] → [Sinks]
Order matters: sampling before formatting saves CPU. Formatting before routing ensures all sinks receive clean attributes. Reversing this wastes work on records that get dropped.
| Library | Purpose | Key constructors |
|---|---|---|
slog-multi | Handler composition | Fanout, Router, FirstMatch, Failover, Pool, Pipe |
slog-sampling | Throughput control | , , , |
Six composition patterns, each for a different routing need:
| Pattern | Behavior | Latency impact |
|---|---|---|
Fanout(handlers...) | Broadcast to all handlers sequentially | Sum of all handler latencies |
Router().Add(h, predicate).Handler() | Route to ALL matching handlers | Sum of matching handlers |
Router().Add(...).FirstMatch().Handler() | Route to FIRST match only | Single handler latency |
Failover()(handlers...) | Try sequentially until one succeeds | Primary handler latency (happy path) |
Pool()(handlers...) |
// Route errors to Sentry, all logs to stdout
logger := slog.New(
slogmulti.Router().
Add(sentryHandler, slogmulti.LevelIs(slog.LevelError)).
Add(slog.NewJSONHandler(os.Stdout, nil)).
Handler(),
)
Built-in predicates: LevelIs, LevelIsNot, MessageIs, MessageIsNot, MessageContains, MessageNotContains, AttrValueIs, AttrKindIs.
For full code examples of every pattern, see Pipeline Patterns.
| Strategy | Behavior | Best for |
|---|---|---|
| Uniform | Drop fixed % of all records | Dev/staging noise reduction |
| Threshold | Log first N per interval, then sample at rate R | Production — preserves initial visibility |
| Absolute | Cap at N records per interval globally | Hard cost control |
| Custom | User function returns sample rate per record | Level-aware or time-aware rules |
Sampling MUST be the outermost handler in the pipeline — placing it after formatting wastes CPU on records that get dropped.
// Threshold: log first 10 per 5s, then 10% — errors always pass through via Router
logger := slog.New(
slogmulti.
Pipe(slogsampling.ThresholdSamplingOption{
Tick: 5 * time.Second, Threshold: 10, Rate: 0.1,
}.NewMiddleware()).
Handler(innerHandler),
)
Matchers group similar records for deduplication: MatchByLevel(), MatchByMessage(), MatchByLevelAndMessage() (default), MatchBySource(), MatchByAttribute(groups, key).
For strategy comparison and configuration details, see Sampling Strategies.
Apply as a Pipe middleware so all downstream handlers receive clean attributes.
logger := slog.New(
slogmulti.Pipe(slogformatter.NewFormatterMiddleware(
slogformatter.PIIFormatter("user"), // mask PII fields
slogformatter.ErrorFormatter("error"), // structured error info
slogformatter.IPAddressFormatter("client"), // mask IP addresses
)).Handler(slog.NewJSONHandler(os.Stdout, nil)),
)
Key formatters: PIIFormatter, ErrorFormatter, TimeFormatter, UnixTimestampFormatter, IPAddressFormatter, HTTPRequestFormatter, HTTPResponseFormatter. Generic formatters: FormatByType[T], FormatByKey, FormatByKind, FormatByGroup, . Flatten nested attributes with .
Consistent pattern across frameworks: router.Use(slogXXX.New(logger)).
Available: slog-gin, slog-echo, slog-fiber, slog-chi, slog-http (net/http).
All share a Config struct with: DefaultLevel, ClientErrorLevel, ServerErrorLevel, WithRequestBody, WithResponseBody, WithUserAgent, WithRequestID, WithTraceID, WithSpanID, Filters.
// Gin with filters — skip health checks
router.Use(sloggin.NewWithConfig(logger, sloggin.Config{
DefaultLevel: slog.LevelInfo,
ClientErrorLevel: slog.LevelWarn,
ServerErrorLevel: slog.LevelError,
WithRequestBody: true,
Filters: []sloggin.Filter{
sloggin.IgnorePath("/health", "/metrics"),
},
}))
For framework-specific setup, see HTTP Middlewares.
All follow the Option{}.NewXxxHandler() constructor pattern.
| Category | Packages |
|---|---|
| Cloud | slog-datadog, slog-sentry, slog-loki, slog-graylog |
| Messaging | slog-kafka, slog-fluentd, slog-logstash, slog-nats |
| Notification | slog-slack, , |
Batch handlers require graceful shutdown — slog-datadog, slog-loki, slog-kafka, and slog-parquet buffer records internally. Flush on shutdown (e.g., handler.Stop(ctx) for Datadog, lokiClient.Stop() for Loki, writer.Close() for Kafka) or buffered logs are lost.
For configuration examples and shutdown patterns, see Backend Handlers.
| Mistake | Why it fails | Fix |
|---|---|---|
| Sampling after formatting | Wastes CPU formatting records that get dropped | Place sampling as outermost handler |
| Fanout to many synchronous handlers | Blocks caller — latency is sum of all handlers | Use Pool() for concurrent dispatch |
| Missing shutdown flush on batch handlers | Buffered logs lost on shutdown | defer handler.Stop(ctx) (Datadog), defer lokiClient.Stop() (Loki), defer writer.Close() (Kafka) |
| Router without default/catch-all handler | Unmatched records silently dropped | Add a handler with no predicate as catch-all |
| without HTTP middleware |
Pool() to reduce to max(latencies)slog.LogValuer on your types insteadgo test -bench before production deploymentDiagnose: measure per-record allocation and latency of your pipeline and identify which handler in the chain allocates most.
slogmulti.NewHandleInlineHandler — assert on records reaching each stage without real sinksAttrFromContext to propagate request-scoped attributes from HTTP middleware to all handlerssamber/cc-skills-golang@golang-observability skill for slog fundamentals (levels, context, handler setup, migration)samber/cc-skills-golang@golang-error-handling skill for the log-or-return rulesamber/cc-skills-golang@golang-security skill for PII handling in logssamber/cc-skills-golang@golang-samber-oops skill for structured error context with samber/oopsIf you encounter a bug or unexpected behavior in any samber/slog-* package, open an issue at the relevant repository (e.g., slog-multi/issues, slog-sampling/issues).
Weekly Installs
69
Repository
GitHub Stars
184
First Seen
3 days ago
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode67
codex66
gemini-cli66
github-copilot65
kimi-cli65
amp65
Laravel架构模式指南:生产级开发模式与最佳实践
1,100 周安装
Hyvä Alpine 组件开发指南:编写兼容 CSP 的 Alpine.js 代码,满足 PCI-DSS 4.0 标准
218 周安装
TypeScript单元测试指南:Jest与NestJS测试工作流与最佳实践
214 周安装
Eve Horizon 新项目设置指南:从初始化到部署的完整配置流程
220 周安装
AI求职信生成器 - 个性化定制专业求职信与工作申请,提升求职成功率
213 周安装
Nansen Token Research CLI - 区块链代币深度分析工具,获取价格、持有者、资金流数据
217 周安装
参考文档创建器 - 基于技术栈智能生成ADR、指南和手册的自动化工具
215 周安装
UniformSamplingOptionThresholdSamplingOptionAbsoluteSamplingOptionCustomSamplingOptionslog-formatter | Attribute transforms | PIIFormatter, ErrorFormatter, FormatByType[T], FormatByKey, FlattenFormatterMiddleware |
| Concurrent broadcast to all handlers |
| Max of all handler latencies |
Pipe(middlewares...).Handler(sink) | Middleware chain before sink | Middleware overhead + sink |
FormatByGroupKeyFlattenFormatterMiddlewareslog-telegramslog-webhook| Storage | slog-parquet |
| Bridges | slog-zap, slog-zerolog, slog-logrus |
AttrFromContext| Context has no request attributes to extract |
Install slog-gin/echo/fiber/chi middleware first |
Using Pipe with no middleware | No-op wrapper adding per-record overhead | Remove Pipe() if no middleware needed |