From fadd469e69c98df99d6176256c989211a258c912 Mon Sep 17 00:00:00 2001 From: Ankur Shrivastava Date: Fri, 27 Mar 2026 21:54:37 +0800 Subject: [PATCH 1/3] docs: update for slog default backend and gokit/logrus deprecation - Index.md: update structured logging feature to mention slog as default - Packages.md: update log description with slog default and deprecation notes - howto/Log.md: add "Logging backends" section with backend table, slog configuration example, slog bridge setup, and deprecation notice --- Index.md | 3 ++- Packages.md | 2 +- howto/Log.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 51 insertions(+), 2 deletions(-) diff --git a/Index.md b/Index.md index 9c09f4b..592ccfa 100644 --- a/Index.md +++ b/Index.md @@ -26,7 +26,7 @@ A Kubernetes-native Go microservice framework for building production-grade gRPC | Feature | Description | |---------|-------------| | **gRPC + REST Gateway** | Define your API once in protobuf — get gRPC, REST, and [Swagger docs](/architecture#self-documenting-apis) automatically via [grpc-gateway] | -| **Structured Logging** | Pluggable backends (go-kit, zap, logrus) with per-request context fields and trace ID propagation | +| **Structured Logging** | Pluggable backends — [slog] (default), zap, go-kit, logrus — with per-request context fields and trace ID propagation | | **Distributed Tracing** | [OpenTelemetry], [Jaeger], and [New Relic] support with automatic span creation in interceptors | | **Prometheus Metrics** | Built-in request latency, error rate, and circuit breaker metrics at `/metrics` | | **Error Tracking** | Stack traces, gRPC status codes, and async notification to [Sentry], Rollbar, or Airbrake | @@ -165,3 +165,4 @@ ColdBrew integrates with the tools you already use: [automaxprocs]: https://github.com/uber-go/automaxprocs [GitHub Actions]: https://github.com/features/actions [GitLab CI]: https://docs.gitlab.com/ci/ +[slog]: https://pkg.go.dev/log/slog diff --git a/Packages.md b/Packages.md index 3551e5f..3387d2b 100644 --- a/Packages.md +++ b/Packages.md @@ -25,7 +25,7 @@ ColdBrew config package contains the configuration for the core package. It uses Documentation can be found at [config-docs] ## [Log] -log provides a minimal interface for structured logging in services. It provides a simple interface to log errors, warnings, info and debug messages. It also provides a mechanism to add contextual information to logs. We provide implementations for gokit, logrus and zap. +log provides a minimal interface for structured logging in services. It provides a simple interface to log errors, warnings, info and debug messages. It also provides a mechanism to add contextual information to logs. The default backend is [slog](https://pkg.go.dev/log/slog) (Go's standard structured logging). We also provide implementations for zap, gokit (deprecated), and logrus (deprecated). A bidirectional slog bridge allows third-party code using `slog` natively to flow through ColdBrew's logging pipeline. Documentation can be found at [log-docs] diff --git a/howto/Log.md b/howto/Log.md index 2e5f266..5b3d4ff 100644 --- a/howto/Log.md +++ b/howto/Log.md @@ -10,6 +10,54 @@ description: "Context-aware logging and trace ID propagation in ColdBrew" 1. TOC {:toc} +## Logging backends + +ColdBrew's log package supports pluggable backends. The default is **slog** (Go's standard structured logging, since v0.2.8). + +| Backend | Package | Status | +|---------|---------|--------| +| **slog** | `loggers/slog` | Default, recommended | +| **zap** | `loggers/zap` | Supported | +| **gokit** | `loggers/gokit` | Deprecated | +| **logrus** | `loggers/logrus` | Deprecated | +| **stdlog** | `loggers/stdlog` | Minimal, for simple use cases | + +To explicitly configure a backend: + +```go +import ( + "github.com/go-coldbrew/log" + "github.com/go-coldbrew/log/loggers" + cbslog "github.com/go-coldbrew/log/loggers/slog" +) + +func init() { + log.SetLogger(log.NewLogger(cbslog.NewLogger( + loggers.WithJSONLogs(true), + loggers.WithCallerInfo(true), + ))) +} +``` + +### slog bridge + +If your application or third-party libraries use `slog` directly, you can route those calls through ColdBrew's logging pipeline (context fields, level overrides, interceptors): + +```go +import ( + "log/slog" + "github.com/go-coldbrew/log" + "github.com/go-coldbrew/log/wrap" +) + +func init() { + slog.SetDefault(wrap.ToSlogLogger(log.GetLogger())) +} +``` + +{: .note } +The gokit and logrus backends are deprecated. Both upstream libraries are in maintenance mode and no longer actively developed. Migrate to the slog backend for better performance and long-term support. + ## Context aware logs In any service there a set of common items that you want to log with every log message. These items are usually things like the request-id, trace, user-id, etc. It is useful to have these items in the log message so that you can filter on them in your log aggregation system. This is especially useful when you have multiple points of logs and you want to be able to trace a request through the system. From 06f2d7d0d1a95e1ee2eeb03799b9fec40176112d Mon Sep 17 00:00:00 2001 From: Ankur Shrivastava Date: Fri, 27 Mar 2026 22:02:07 +0800 Subject: [PATCH 2/3] Update Packages.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- Packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Packages.md b/Packages.md index 3387d2b..7435882 100644 --- a/Packages.md +++ b/Packages.md @@ -25,7 +25,7 @@ ColdBrew config package contains the configuration for the core package. It uses Documentation can be found at [config-docs] ## [Log] -log provides a minimal interface for structured logging in services. It provides a simple interface to log errors, warnings, info and debug messages. It also provides a mechanism to add contextual information to logs. The default backend is [slog](https://pkg.go.dev/log/slog) (Go's standard structured logging). We also provide implementations for zap, gokit (deprecated), and logrus (deprecated). A bidirectional slog bridge allows third-party code using `slog` natively to flow through ColdBrew's logging pipeline. +log provides a minimal interface for structured logging in services. It provides a simple interface to log errors, warnings, info and debug messages. It also provides a mechanism to add contextual information to logs. The default backend is [slog](https://pkg.go.dev/log/slog) (Go's standard structured logging). We also provide implementations for zap, gokit (deprecated), and logrus (deprecated). A slog bridge allows third-party code that uses `slog` directly to route its logs through ColdBrew's logging pipeline. Documentation can be found at [log-docs] From 1ba9e6d6034a071a8f4a82717ad978a621494cba Mon Sep 17 00:00:00 2001 From: Ankur Shrivastava Date: Fri, 27 Mar 2026 22:02:15 +0800 Subject: [PATCH 3/3] Update howto/Log.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- howto/Log.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/howto/Log.md b/howto/Log.md index 5b3d4ff..61e7a53 100644 --- a/howto/Log.md +++ b/howto/Log.md @@ -12,7 +12,7 @@ description: "Context-aware logging and trace ID propagation in ColdBrew" ## Logging backends -ColdBrew's log package supports pluggable backends. The default is **slog** (Go's standard structured logging, since v0.2.8). +ColdBrew's log package supports pluggable backends. The default is **slog** (Go's standard structured logging). | Backend | Package | Status | |---------|---------|--------|