Golang Samber Slog

1---2name: golang-samber-slog3description: "Structured logging extensions for Golang using samber/slog-**** packages — multi-handler pipelines (slog-multi), log sampling (slog-sampling), attribute formatting (slog-formatter), HTTP middleware (slog-fiber, slog-gin, slog-chi, slog-echo), and backend routing (slog-datadog, slog-sentry, slog-loki, slog-syslog, slog-logstash, slog-graylog...). Apply when using or adopting slog, or when the codebase already imports any github.com/samber/slog-* package."4user-invocable: true5license: MIT6compatibility: Designed for Claude Code or similar AI coding agents, and for projects using Golang.7metadata:8  author: samber9  version: "1.0.3"10  openclaw:11    emoji: "🪵"12    homepage: https://github.com/samber/cc-skills-golang13    requires:14      bins:15        - go16    install: []17    skill-library-version:18      slog-multi: "1.8.0"19      slog-sampling: "1.6.0"20      slog-formatter: "1.3.0"21      slog-fiber: "1.22.1"22      slog-gin: "1.21.0"23      slog-chi: "1.19.0"24      slog-echo: "1.21.0"25      slog-http: "1.12.0"26      slog-betterstack: "1.4.4"27      slog-channel: "1.4.4"28      slog-datadog: "2.10.4"29      slog-sentry: "2.10.3"30      slog-loki: "3.7.2"31      slog-syslog: "2.5.4"32      slog-logstash: "2.6.4"33      slog-graylog: "2.7.5"34      slog-fluentd: "2.5.4"35      slog-kafka: "2.6.5"36      slog-logrus: "2.5.4"37      slog-zap: "2.6.4"38      slog-zerolog: "2.9.2"39      slog-slack: "2.7.5"40      slog-telegram: "2.4.4"41      slog-webhook: "2.8.4"42      slog-mattermost: "2.5.4"43      slog-microsoft-teams: "2.7.4"44      slog-nats: "0.4.5"45      slog-otel: "0.1.0"46      slog-parquet: "2.5.2"47      slog-quickwit: "0.3.4"48      slog-rollbar: "2.7.4"49      slog-mock: "0.1.0"50allowed-tools: Read Edit Write Glob Grep Bash(go:*) Bash(golangci-lint:*) Bash(git:*) Agent WebFetch mcp__context7__resolve-library-id mcp__context7__query-docs AskUserQuestion51---52 53**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.54 55# samber/slog-\*\*\*\* — Structured Logging Pipeline for Go56 5720+ 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.58 59**Official resources:**60 61- [github.com/samber/slog-multi](https://github.com/samber/slog-multi) — handler composition62- [github.com/samber/slog-sampling](https://github.com/samber/slog-sampling) — throughput control63- [github.com/samber/slog-formatter](https://github.com/samber/slog-formatter) — attribute transformation64 65This skill is not exhaustive. Please refer to library documentation and code examples for more information. Context7 can help as a discoverability platform.66 67## The Pipeline Model68 69Every 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.70 71```72record → [Sampling] → [Pipe: trace/PII] → [Router] → [Sinks]73```74 75Order matters: sampling before formatting saves CPU. Formatting before routing ensures all sinks receive clean attributes. Reversing this wastes work on records that get dropped.76 77## Core Libraries78 79| Library | Purpose | Key constructors |80| --- | --- | --- |81| `slog-multi` | Handler composition | `Fanout`, `Router`, `FirstMatch`, `Failover`, `Pool`, `Pipe` |82| `slog-sampling` | Throughput control | `UniformSamplingOption`, `ThresholdSamplingOption`, `AbsoluteSamplingOption`, `CustomSamplingOption` |83| `slog-formatter` | Attribute transforms | `PIIFormatter`, `ErrorFormatter`, `FormatByType[T]`, `FormatByKey`, `FlattenFormatterMiddleware` |84 85## slog-multi — Handler Composition86 87Six composition patterns, each for a different routing need:88 89| Pattern | Behavior | Latency impact |90| --- | --- | --- |91| `Fanout(handlers...)` | Broadcast to all handlers sequentially | Sum of all handler latencies |92| `Router().Add(h, predicate).Handler()` | Route to ALL matching handlers | Sum of matching handlers |93| `Router().Add(...).FirstMatch().Handler()` | Route to FIRST match only | Single handler latency |94| `Failover()(handlers...)` | Try sequentially until one succeeds | Primary handler latency (happy path) |95| `Pool()(handlers...)` | Concurrent broadcast to all handlers | Max of all handler latencies |96| `Pipe(middlewares...).Handler(sink)` | Middleware chain before sink | Middleware overhead + sink |97 98```go99// Route errors to Sentry, all logs to stdout100logger := slog.New(101    slogmulti.Router().102        Add(sentryHandler, slogmulti.LevelIs(slog.LevelError)).103        Add(slog.NewJSONHandler(os.Stdout, nil)).104        Handler(),105)106```107 108Built-in predicates: `LevelIs`, `LevelIsNot`, `MessageIs`, `MessageIsNot`, `MessageContains`, `MessageNotContains`, `AttrValueIs`, `AttrKindIs`.109 110For full code examples of every pattern, see [Pipeline Patterns](references/pipeline-patterns.md).111 112## slog-sampling — Throughput Control113 114| Strategy | Behavior | Best for |115| --- | --- | --- |116| Uniform | Drop fixed % of all records | Dev/staging noise reduction |117| Threshold | Log first N per interval, then sample at rate R | Production — preserves initial visibility |118| Absolute | Cap at N records per interval globally | Hard cost control |119| Custom | User function returns sample rate per record | Level-aware or time-aware rules |120 121Sampling MUST be the outermost handler in the pipeline — placing it after formatting wastes CPU on records that get dropped.122 123```go124// Threshold: log first 10 per 5s, then 10% — errors always pass through via Router125logger := slog.New(126    slogmulti.127        Pipe(slogsampling.ThresholdSamplingOption{128            Tick: 5 * time.Second, Threshold: 10, Rate: 0.1,129        }.NewMiddleware()).130        Handler(innerHandler),131)132```133 134Matchers group similar records for deduplication: `MatchByLevel()`, `MatchByMessage()`, `MatchByLevelAndMessage()` (default), `MatchBySource()`, `MatchByAttribute(groups, key)`.135 136For strategy comparison and configuration details, see [Sampling Strategies](references/sampling-strategies.md).137 138## slog-formatter — Attribute Transformation139 140Apply as a `Pipe` middleware so all downstream handlers receive clean attributes.141 142```go143logger := slog.New(144    slogmulti.Pipe(slogformatter.NewFormatterMiddleware(145        slogformatter.PIIFormatter("user"),          // mask PII fields146        slogformatter.ErrorFormatter("error"),       // structured error info147        slogformatter.IPAddressFormatter("client"),  // mask IP addresses148    )).Handler(slog.NewJSONHandler(os.Stdout, nil)),149)150```151 152Key formatters: `PIIFormatter`, `ErrorFormatter`, `TimeFormatter`, `UnixTimestampFormatter`, `IPAddressFormatter`, `HTTPRequestFormatter`, `HTTPResponseFormatter`. Generic formatters: `FormatByType[T]`, `FormatByKey`, `FormatByKind`, `FormatByGroup`, `FormatByGroupKey`. Flatten nested attributes with `FlattenFormatterMiddleware`.153 154## HTTP Middlewares155 156Consistent pattern across frameworks: `router.Use(slogXXX.New(logger))`.157 158Available: `slog-gin`, `slog-echo`, `slog-fiber`, `slog-chi`, `slog-http` (net/http).159 160All share a `Config` struct with: `DefaultLevel`, `ClientErrorLevel`, `ServerErrorLevel`, `WithRequestBody`, `WithResponseBody`, `WithUserAgent`, `WithRequestID`, `WithTraceID`, `WithSpanID`, `Filters`.161 162```go163// Gin with filters — skip health checks164router.Use(sloggin.NewWithConfig(logger, sloggin.Config{165    DefaultLevel:     slog.LevelInfo,166    ClientErrorLevel: slog.LevelWarn,167    ServerErrorLevel: slog.LevelError,168    WithRequestBody:  true,169    Filters: []sloggin.Filter{170        sloggin.IgnorePath("/health", "/metrics"),171    },172}))173```174 175For framework-specific setup, see [HTTP Middlewares](references/http-middlewares.md).176 177## Backend Sinks178 179All follow the `Option{}.NewXxxHandler()` constructor pattern.180 181| Category     | Packages                                                   |182| ------------ | ---------------------------------------------------------- |183| Cloud        | `slog-datadog`, `slog-sentry`, `slog-loki`, `slog-graylog` |184| Messaging    | `slog-kafka`, `slog-fluentd`, `slog-logstash`, `slog-nats` |185| Notification | `slog-slack`, `slog-telegram`, `slog-webhook`              |186| Storage      | `slog-parquet`                                             |187| Bridges      | `slog-zap`, `slog-zerolog`, `slog-logrus`                  |188 189**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.190 191For configuration examples and shutdown patterns, see [Backend Handlers](references/backend-handlers.md).192 193## Common Mistakes194 195| Mistake | Why it fails | Fix |196| --- | --- | --- |197| Sampling after formatting | Wastes CPU formatting records that get dropped | Place sampling as outermost handler |198| Fanout to many synchronous handlers | Blocks caller — latency is sum of all handlers | Use `Pool()` for concurrent dispatch |199| Missing shutdown flush on batch handlers | Buffered logs lost on shutdown | `defer handler.Stop(ctx)` (Datadog), `defer lokiClient.Stop()` (Loki), `defer writer.Close()` (Kafka) |200| Router without default/catch-all handler | Unmatched records silently dropped | Add a handler with no predicate as catch-all |201| `AttrFromContext` without HTTP middleware | Context has no request attributes to extract | Install `slog-gin`/`echo`/`fiber`/`chi` middleware first |202| Using `Pipe` with no middleware | No-op wrapper adding per-record overhead | Remove `Pipe()` if no middleware needed |203 204## Performance Warnings205 206- **Fanout latency** = sum of all handler latencies (sequential). With 5 handlers at 10ms each, every log call costs 50ms. Use `Pool()` to reduce to max(latencies)207- **Pipe middleware** adds per-record function call overhead — keep chains short (2-4 middlewares)208- **slog-formatter** processes attributes sequentially — many formatters compound. For hot-path attribute formatting, prefer implementing `slog.LogValuer` on your types instead209- **Benchmark** your pipeline with `go test -bench` before production deployment210 211**Diagnose:** measure per-record allocation and latency of your pipeline and identify which handler in the chain allocates most.212 213## Best Practices214 2151. **Sample first, format second, route last** — this canonical ordering minimizes wasted work and ensures all sinks see clean data2162. **Use Pipe for cross-cutting concerns** — trace ID injection and PII scrubbing belong in middleware, not per-handler logic2173. **Test pipelines with `slogmulti.NewHandleInlineHandler`** — assert on records reaching each stage without real sinks2184. **Use `AttrFromContext`** to propagate request-scoped attributes from HTTP middleware to all handlers2195. **Prefer Router over Fanout** when handlers need different record subsets — Router evaluates predicates and skips non-matching handlers220 221## Cross-References222 223- → See `samber/cc-skills-golang@golang-observability` skill for slog fundamentals (levels, context, handler setup, migration)224- → See `samber/cc-skills-golang@golang-error-handling` skill for the log-or-return rule225- → See `samber/cc-skills-golang@golang-security` skill for PII handling in logs226- → See `samber/cc-skills-golang@golang-samber-oops` skill for structured error context with `samber/oops`227 228If you encounter a bug or unexpected behavior in any samber/slog-\* package, open an issue at the relevant repository (e.g., [slog-multi/issues](https://github.com/samber/slog-multi/issues), [slog-sampling/issues](https://github.com/samber/slog-sampling/issues)).