sloggin

README

slog: Gin middleware

Gin middleware to log http requests using slog.

---

^{Sponsored by:}

Cloud-native search engine for observability - An OSS alternative to Splunk, Elasticsearch, Loki, and Tempo.

---

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

🚀 Install

go get github.com/samber/slog-gin

Compatibility: go >= 1.21

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

💡 Usage

Handler options

type Config struct {
	DefaultLevel     slog.Level
	ClientErrorLevel slog.Level
	ServerErrorLevel slog.Level

	WithUserAgent      bool
	WithRequestID      bool
	WithRequestBody    bool
	WithRequestHeader  bool
	WithResponseBody   bool
	WithResponseHeader bool
	WithSpanID         bool
	WithTraceID        bool

	Filters []Filter
}

Attributes will be injected in log payload.

Other global parameters:

sloggin.TraceIDKey = "trace_id"
sloggin.SpanIDKey = "span_id"
sloggin.RequestBodyMaxSize  = 64 * 1024 // 64KB
sloggin.ResponseBodyMaxSize = 64 * 1024 // 64KB
sloggin.HiddenRequestHeaders = map[string]struct{}{ ... }
sloggin.HiddenResponseHeaders = map[string]struct{}{ ... }
sloggin.RequestIDHeaderKey = "X-Request-Id"

Minimal

import (
	"github.com/gin-gonic/gin"
	sloggin "github.com/samber/slog-gin"
	"log/slog"
)

// Create a slog logger, which:
//   - Logs to stdout.
logger := slog.New(slog.NewTextHandler(os.Stdout, nil))

router := gin.New()

// Add the sloggin middleware to all routes.
// The middleware will log all requests attributes.
router.Use(sloggin.New(logger))
router.Use(gin.Recovery())

// Example pong request.
router.GET("/pong", func(c *gin.Context) {
    c.String(http.StatusOK, "pong")
})

router.Run(":1234")

// output:
// time=2023-10-15T20:32:58.926+02:00 level=INFO msg="Incoming request" env=production request.time=2023-10-15T20:32:58.626+02:00 request.method=GET request.path=/ request.query="" request.route="" request.ip=127.0.0.1:63932 request.length=0 response.time=2023-10-15T20:32:58.926+02:00 response.latency=100ms response.status=200 response.length=7 id=""

OTEL

logger := slog.New(slog.NewTextHandler(os.Stdout, nil))

config := sloggin.Config{
	WithSpanID:  true,
	WithTraceID: true,
}

router := gin.New()
router.Use(sloggin.NewWithConfig(logger, config))

Custom log levels

logger := slog.New(slog.NewTextHandler(os.Stdout, nil))

config := sloggin.Config{
	DefaultLevel:     slog.LevelInfo,
	ClientErrorLevel: slog.LevelWarn,
	ServerErrorLevel: slog.LevelError,
}

router := gin.New()
router.Use(sloggin.NewWithConfig(logger, config))

Verbose

logger := slog.New(slog.NewTextHandler(os.Stdout, nil))

config := sloggin.Config{
	WithRequestBody: true,
	WithResponseBody: true,
	WithRequestHeader: true,
	WithResponseHeader: true,
}

router := gin.New()
router.Use(sloggin.NewWithConfig(logger, config))

Filters

logger := slog.New(slog.NewTextHandler(os.Stdout, nil))

router := gin.New()
router.Use(
	sloggin.NewWithFilters(
		logger,
		sloggin.Accept(func (c *gin.Context) bool {
			return xxx
		}),
		sloggin.IgnoreStatus(401, 404),
	),
)

Available filters:

• Accept / Ignore
• AcceptMethod / IgnoreMethod
• AcceptStatus / IgnoreStatus
• AcceptStatusGreaterThan / IgnoreStatusLessThan
• AcceptStatusGreaterThanOrEqual / IgnoreStatusLessThanOrEqual
• AcceptPath / IgnorePath
• AcceptPathContains / IgnorePathContains
• AcceptPathPrefix / IgnorePathPrefix
• AcceptPathSuffix / IgnorePathSuffix
• AcceptPathMatch / IgnorePathMatch
• AcceptHost / IgnoreHost
• AcceptHostContains / IgnoreHostContains
• AcceptHostPrefix / IgnoreHostPrefix
• AcceptHostSuffix / IgnoreHostSuffix
• AcceptHostMatch / IgnoreHostMatch

Using custom time formatters

import (
	"github.com/gin-gonic/gin"
	sloggin "github.com/samber/slog-gin"
	slogformatter "github.com/samber/slog-formatter"
	"log/slog"
)

// Create a slog logger, which:
//   - Logs to stdout.
//   - RFC3339 with UTC time format.
logger := slog.New(
    slogformatter.NewFormatterHandler(
        slogformatter.TimezoneConverter(time.UTC),
        slogformatter.TimeFormatter(time.DateTime, nil),
    )(
        slog.NewTextHandler(os.Stdout, nil),
    ),
)

router := gin.New()

// Add the sloggin middleware to all routes.
// The middleware will log all requests attributes.
router.Use(sloggin.New(logger))
router.Use(gin.Recovery())

// Example pong request.
router.GET("/pong", func(c *gin.Context) {
    c.String(http.StatusOK, "pong")
})

router.Run(":1234")

// output:
// time=2023-10-15T20:32:58.926+02:00 level=INFO msg="Incoming request" env=production request.time=2023-10-15T20:32:58Z request.method=GET request.path=/ request.query="" request.route="" request.ip=127.0.0.1:63932 request.length=0 response.time=2023-10-15T20:32:58Z response.latency=100ms response.status=200 response.length=7 id=""

Using custom logger sub-group

logger := slog.New(slog.NewTextHandler(os.Stdout, nil))

router := gin.New()

// Add the sloggin middleware to all routes.
// The middleware will log all requests attributes under a "http" group.
router.Use(sloggin.New(logger.WithGroup("http")))
router.Use(gin.Recovery())

// Example pong request.
router.GET("/pong", func(c *gin.Context) {
    c.String(http.StatusOK, "pong")
})

router.Run(":1234")

// output:
// time=2023-10-15T20:32:58.926+02:00 level=INFO msg="Incoming request" env=production http.request.time=2023-10-15T20:32:58.626+02:00 http.request.method=GET http.request.path=/ request.query="" http.request.route="" http.request.ip=127.0.0.1:63932 http.request.length=0 http.response.time=2023-10-15T20:32:58.926+02:00 http.response.latency=100ms http.response.status=200 http.response.length=7 http.id=""

Add logger to a single route

logger := slog.New(slog.NewTextHandler(os.Stdout, nil))

router := gin.New()
router.Use(gin.Recovery())

// Example pong request.
// Add the sloggin middleware to a single routes.
router.GET("/pong", sloggin.New(logger), func(c *gin.Context) {
    c.String(http.StatusOK, "pong")
})

router.Run(":1234")

Adding custom attributes

logger := slog.New(slog.NewTextHandler(os.Stdout, nil)).
    With("environment", "production").
    With("server", "gin/1.9.0").
    With("server_start_time", time.Now()).
    With("gin_mode", gin.EnvGinMode)

router := gin.New()

// Add the sloggin middleware to all routes.
// The middleware will log all requests attributes.
router.Use(sloggin.New(logger))
router.Use(gin.Recovery())

// Example pong request.
router.GET("/pong", func(c *gin.Context) {
	// Add an attribute to a single log entry.
	sloggin.AddCustomAttributes(c, slog.String("foo", "bar"))
    c.String(http.StatusOK, "pong")
})

router.Run(":1234")

// output:
// time=2023-10-15T20:32:58.926+02:00 level=INFO msg="Incoming request" environment=production server=gin/1.9.0 gin_mode=release request.time=2023-10-15T20:32:58.626+02:00 request.method=GET request.path=/ request.query="" request.route="" request.ip=127.0.0.1:63932 request.length=0 response.time=2023-10-15T20:32:58.926+02:00 response.latency=100ms response.status=200 response.length=7 id="" foo=bar

JSON output

logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))

router := gin.New()

// Add the sloggin middleware to all routes.
// The middleware will log all requests attributes.
router.Use(sloggin.New(logger))
router.Use(gin.Recovery())

// Example pong request.
router.GET("/pong", func(c *gin.Context) {
    c.String(http.StatusOK, "pong")
})

router.Run(":1234")

// output:
// {"time":"2023-10-15T20:32:58.926+02:00","level":"INFO","msg":"Incoming request","gin_mode":"GIN_MODE","env":"production","http":{"request":{"time":"2023-10-15T20:32:58.626+02:00","method":"GET","path":"/","query":"","route":"","ip":"127.0.0.1:55296","length":0},"response":{"time":"2023-10-15T20:32:58.926+02:00","latency":100000,"status":200,"length":7},"id":""}}

🤝 Contributing

• Ping me on twitter @samuelberthe (DMs, mentions, whatever :))
• Fork the project
• Fix open issues or request new features

Don't hesitate ;)

# Install some dev dependencies
make tools

# Run tests
make test
# or
make watch-test

👤 Contributors

💫 Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2023 Samuel Berthe.

This project is MIT licensed.

Documentation

Index

• Variables
• func AddCustomAttributes(c *gin.Context, attr slog.Attr)
• func GetRequestID(c *gin.Context) string
• func New(logger *slog.Logger) gin.HandlerFunc
• func NewWithConfig(logger *slog.Logger, config Config) gin.HandlerFunc
• func NewWithFilters(logger *slog.Logger, filters ...Filter) gin.HandlerFunc
• type Config
• type Filter
  • func Accept(filter Filter) Filter
  • func AcceptHost(hosts ...string) Filter
  • func AcceptHostContains(parts ...string) Filter
  • func AcceptHostMatch(regs ...regexp.Regexp) Filter
  • func AcceptHostPrefix(prefixs ...string) Filter
  • func AcceptHostSuffix(prefixs ...string) Filter
  • func AcceptMethod(methods ...string) Filter
  • func AcceptPath(urls ...string) Filter
  • func AcceptPathContains(parts ...string) Filter
  • func AcceptPathMatch(regs ...regexp.Regexp) Filter
  • func AcceptPathPrefix(prefixs ...string) Filter
  • func AcceptPathSuffix(prefixs ...string) Filter
  • func AcceptStatus(statuses ...int) Filter
  • func AcceptStatusGreaterThan(status int) Filter
  • func AcceptStatusGreaterThanOrEqual(status int) Filter
  • func Ignore(filter Filter) Filter
  • func IgnoreHost(hosts ...string) Filter
  • func IgnoreHostContains(parts ...string) Filter
  • func IgnoreHostMatch(regs ...regexp.Regexp) Filter
  • func IgnoreHostPrefix(prefixs ...string) Filter
  • func IgnoreHostSuffix(suffixs ...string) Filter
  • func IgnoreMethod(methods ...string) Filter
  • func IgnorePath(urls ...string) Filter
  • func IgnorePathContains(parts ...string) Filter
  • func IgnorePathMatch(regs ...regexp.Regexp) Filter
  • func IgnorePathPrefix(prefixs ...string) Filter
  • func IgnorePathSuffix(suffixs ...string) Filter
  • func IgnoreStatus(statuses ...int) Filter
  • func IgnoreStatusLessThan(status int) Filter
  • func IgnoreStatusLessThanOrEqual(status int) Filter

Variables

var (
	TraceIDKey   = "trace_id"
	SpanIDKey    = "span_id"
	RequestIDKey = "id"

	RequestBodyMaxSize  = 64 * 1024 // 64KB
	ResponseBodyMaxSize = 64 * 1024 // 64KB

	HiddenRequestHeaders = map[string]struct{}{
		"authorization": {},
		"cookie":        {},
		"set-cookie":    {},
		"x-auth-token":  {},
		"x-csrf-token":  {},
		"x-xsrf-token":  {},
	}
	HiddenResponseHeaders = map[string]struct{}{
		"set-cookie": {},
	}

	// Formatted with http.CanonicalHeaderKey
	RequestIDHeaderKey = "X-Request-Id"
)

Functions

func AddCustomAttributes

func AddCustomAttributes(c *gin.Context, attr slog.Attr)

AddCustomAttributes adds custom attributes to the request context.

func GetRequestID

func GetRequestID(c *gin.Context) string

GetRequestID returns the request identifier.

func New

func New(logger *slog.Logger) gin.HandlerFunc

New returns a gin.HandlerFunc (middleware) that logs requests using slog.

Requests with errors are logged using slog.Error(). Requests without errors are logged using slog.Info().

func NewWithConfig

func NewWithConfig(logger *slog.Logger, config Config) gin.HandlerFunc

NewWithConfig returns a gin.HandlerFunc (middleware) that logs requests using slog.

func NewWithFilters

func NewWithFilters(logger *slog.Logger, filters ...Filter) gin.HandlerFunc

NewWithFilters returns a gin.HandlerFunc (middleware) that logs requests using slog.

Requests with errors are logged using slog.Error(). Requests without errors are logged using slog.Info().

Types

type Config

type Config struct {
	DefaultLevel     slog.Level
	ClientErrorLevel slog.Level
	ServerErrorLevel slog.Level

	WithUserAgent      bool
	WithRequestID      bool
	WithRequestBody    bool
	WithRequestHeader  bool
	WithResponseBody   bool
	WithResponseHeader bool
	WithSpanID         bool
	WithTraceID        bool

	Filters []Filter
}

type Filter

type Filter func(ctx *gin.Context) bool

func Accept

func Accept(filter Filter) Filter

Basic

func AcceptHost

func AcceptHost(hosts ...string) Filter

Host

func AcceptHostContains

func AcceptHostContains(parts ...string) Filter

func AcceptHostMatch

func AcceptHostMatch(regs ...regexp.Regexp) Filter

func AcceptHostPrefix

func AcceptHostPrefix(prefixs ...string) Filter

func AcceptHostSuffix

func AcceptHostSuffix(prefixs ...string) Filter

func AcceptMethod

func AcceptMethod(methods ...string) Filter

Method

func AcceptPath

func AcceptPath(urls ...string) Filter

Path

func AcceptPathContains

func AcceptPathContains(parts ...string) Filter

func AcceptPathMatch

func AcceptPathMatch(regs ...regexp.Regexp) Filter

func AcceptPathPrefix

func AcceptPathPrefix(prefixs ...string) Filter

func AcceptPathSuffix

func AcceptPathSuffix(prefixs ...string) Filter

func AcceptStatus

func AcceptStatus(statuses ...int) Filter

Status

func AcceptStatusGreaterThan

func AcceptStatusGreaterThan(status int) Filter

func AcceptStatusGreaterThanOrEqual

func AcceptStatusGreaterThanOrEqual(status int) Filter

func Ignore

func Ignore(filter Filter) Filter

func IgnoreHost

func IgnoreHost(hosts ...string) Filter

func IgnoreHostContains

func IgnoreHostContains(parts ...string) Filter

func IgnoreHostMatch

func IgnoreHostMatch(regs ...regexp.Regexp) Filter

func IgnoreHostPrefix

func IgnoreHostPrefix(prefixs ...string) Filter

func IgnoreHostSuffix

func IgnoreHostSuffix(suffixs ...string) Filter

func IgnoreMethod

func IgnoreMethod(methods ...string) Filter

func IgnorePath

func IgnorePath(urls ...string) Filter

func IgnorePathContains

func IgnorePathContains(parts ...string) Filter

func IgnorePathMatch

func IgnorePathMatch(regs ...regexp.Regexp) Filter

func IgnorePathPrefix

func IgnorePathPrefix(prefixs ...string) Filter

func IgnorePathSuffix

func IgnorePathSuffix(suffixs ...string) Filter

func IgnoreStatus

func IgnoreStatus(statuses ...int) Filter

func IgnoreStatusLessThan

func IgnoreStatusLessThan(status int) Filter

func IgnoreStatusLessThanOrEqual

func IgnoreStatusLessThanOrEqual(status int) Filter