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..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. 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 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] diff --git a/howto/Log.md b/howto/Log.md index 2e5f266..61e7a53 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). + +| 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.