slog-multi

slog-multi: Advanced Handler Composition for Go's Structured Logging (pipelining, fanout, routing, failover...)

slog-multi provides advanced composition patterns for Go's structured logging (slog). It enables you to build sophisticated logging workflows by combining multiple handlers with different strategies for distribution, routing, transformation, and error handling.

Features

• ** Fanout**: Distribute logs to multiple handlers in parallel
• ️ Router: Conditionally route logs based on custom criteria
• ** First Match**: Route logs to the first matching handler only
• ** Failover**: High-availability logging with automatic fallback
• ⚖️ Load Balancing: Distribute load across multiple handlers
• ** Pipeline**: Transform and filter logs with middleware chains
• ️ Error Recovery: Graceful handling of logging failures

Middlewares:

• ⚡ Inline Handlers: Quick implementation of custom handlers
• ** Inline Middleware**: Rapid development of transformation logic

See also:

• slog-multi: slog.Handler chaining, fanout, routing, failover, load balancing...
• slog-formatter: slog attribute formatting
• slog-sampling: slog sampling policy
• slog-mock: slog.Handler for test purposes

HTTP middlewares:

• slog-gin: Gin middleware for slog logger
• slog-echo: Echo middleware for slog logger
• slog-fiber: Fiber middleware for slog logger
• slog-chi: Chi middleware for slog logger
• slog-http: net/http middleware for slog logger

Loggers:

• slog-zap: A slog handler for Zap
• slog-zerolog: A slog handler for Zerolog
• slog-logrus: A slog handler for Logrus

Log sinks:

• slog-datadog: A slog handler for Datadog
• slog-betterstack: A slog handler for Betterstack
• slog-rollbar: A slog handler for Rollbar
• slog-loki: A slog handler for Loki
• slog-sentry: A slog handler for Sentry
• slog-syslog: A slog handler for Syslog
• slog-logstash: A slog handler for Logstash
• slog-fluentd: A slog handler for Fluentd
• slog-graylog: A slog handler for Graylog
• slog-quickwit: A slog handler for Quickwit
• slog-slack: A slog handler for Slack
• slog-telegram: A slog handler for Telegram
• slog-mattermost: A slog handler for Mattermost
• slog-microsoft-teams: A slog handler for Microsoft Teams
• slog-webhook: A slog handler for Webhook
• slog-kafka: A slog handler for Kafka
• slog-nats: A slog handler for NATS
• slog-parquet: A slog handler for Parquet + Object Storage
• slog-channel: A slog handler for Go channels

Installation

go get github.com/samber/slog-multi

Compatibility: go >= 1.21

No breaking changes will be made to exported APIs before v2.0.0.

[!WARNING] Use this library carefully, log processing can be very costly (!)

Excessive logging —with multiple processing steps and destinations— can introduce significant overhead, which is generally undesirable in performance-critical paths. Logging is always expensive, and sometimes, metrics or a sampling strategy are cheaper. The library itself does not generate extra load.

Usage

GoDoc: https://pkg.go.dev/github.com/samber/slog-multi

Broadcast: slogmulti.Fanout()

Distribute logs to multiple slog.Handler in parallel for maximum throughput and redundancy.

…

Stderr output:

time=2023-04-10T14:00:0.000000+00:00 level=ERROR msg="A message" user.id=user-123 user.created_at=2023-04-10T14:00:0.000000+00:00 environment=dev error="an error"

Netcat output:

{
	"time":"2023-04-10T14:00:0.000000+00:00",
	"level":"ERROR",
	"msg":"A message",
	"user":{
		"id":"user-123",
		"created_at":"2023-04-10T14:00:0.000000+00:00"
	},
	"environment":"dev",
	"error":"an error"
}

Routing: slogmulti.Router()

Distribute logs to all matching slog.Handler based on custom criteria like log level, attributes, or business logic.

…

Use Cases:

• Environment-specific logging (dev vs prod)
• Level-based routing (errors to Slack, info to console)
• Business logic routing (user actions vs system events)

First Match Routing: Router().FirstMatch()

Route logs to the first matching handler only, unlike regular routing which sends to all matching handlers. Perfect for priority-based routing where you want exactly one handler to receive each log.

…

Built-in Predicates

Level predicates:

• LevelIs(levels ...slog.Level) - Match specific log levels
• LevelIsNot(levels ...slog.Level) - Exclude specific log levels

Message predicates:

• MessageIs(msg string) - Exact message match
• MessageIsNot(msg string) - Message doesn't match
• MessageContains(part string) - Message contains substring
• MessageNotContains(part string) - Message doesn't contain substring

Attribute predicates:

• AttrValueIs(key, value, ...) - Check attributes have exact values
• AttrKindIs(key, kind, ...) - Check attributes have specific types

Failover: slogmulti.Failover()

Ensure logging reliability by trying multiple handlers in order until one succeeds. Perfect for high-availability scenarios.

…

Use Cases:

• High-availability logging infrastructure
• Disaster recovery scenarios
• Multi-region deployments

Load balancing: slogmulti.Pool()

Distribute logging load across multiple handlers using round-robin with randomization to increase throughput and provide redundancy.

…

go mdw := slogmulti.NewHandleInlineHandler( // simulate "Handle()" method func(ctx context.Context, groups []string, attrs []slog.Attr, record slog.Record) error { // Custom logic here // [...] return nil }, )

```go
mdw := slogmulti.NewInlineHandler(
    // simulate "Enabled()" method
    func(ctx context.Context, groups []string, attrs []slog.Attr, level slog.Level) bool {
        // Custom logic here
        // [...]
        return true
    },
    // simulate "Handle()" method
    func(ctx context.Context, groups []string, attrs []slog.Attr, record slog.Record) error {
        // Custom logic here
        // [...]
        return nil
    },
)

Inline middleware

Inline middleware provides shortcuts to implement middleware functions that hook specific methods.

Hook Enabled() Method

middleware := slogmulti.NewEnabledInlineMiddleware(func(ctx context.Context, level slog.Level, next func(context.Context, slog.Level) bool) bool{
    // Custom logic before calling next
    if level == slog.LevelDebug {
        return false // Skip debug logs
    }
    return next(ctx, level)
})

Hook Handle() Method

middleware := slogmulti.NewHandleInlineMiddleware(func(ctx context.Context, record slog.Record, next func(context.Context, slog.Record) error) error {
    // Add timestamp to all logs
    record.AddAttrs(slog.Time("logged_at", time.Now()))
    return next(ctx, record)
})

Hook WithAttrs() Method

mdw := slogmulti.NewWithAttrsInlineMiddleware(func(attrs []slog.Attr, next func([]slog.Attr) slog.Handler) slog.Handler{
    // Filter out sensitive attributes
    filtered := make([]slog.Attr, 0, len(attrs))
    for _, attr := range attrs {
        if attr.Key != "password" && attr.Key != "token" {
            filtered = append(filtered, attr)
        }
    }
    return next(attrs)
})

Hook WithGroup() Method

mdw := slogmulti.NewWithGroupInlineMiddleware(func(name string, next func(string) slog.Handler) slog.Handler{
    // Add prefix to group names
    prefixedName := "app." + name
    return next(name)
})

Complete Inline Middleware

Warning: You should implement your own middleware for complex scenarios.

mdw := slogmulti.NewInlineMiddleware(
    func(ctx context.Context, level slog.Level, next func(context.Context, slog.Level) bool) bool{
        // Custom logic here
        // [...]
        return next(ctx, level)
    },
    func(ctx context.Context, record slog.Record, next func(context.Context, slog.Record) error) error{
        // Custom logic here
        // [...]
        return next(ctx, record)
    },
    func(attrs []slog.Attr, next func([]slog.Attr) slog.Handler) slog.Handler{
        // Custom logic here
        // [...]
        return next(attrs)
    },
    func(name string, next func(string) slog.Handler) slog.Handler{
        // Custom logic here
        // [...]
        return next(name)
    },
)

…

bash
# Install some dev dependencies
make tools

# Run tests
make test
# or
make watch-test

Contributors

Show your support

If this project helped you, please give it a ⭐️ on GitHub!

License

Copyright © 2023 Samuel Berthe.

This project is MIT licensed.