logger

README

logger

Gin middleware/handler to logger url path using rs/zerolog.

Example

package main

import (
  "fmt"
  "net/http"
  "regexp"
  "time"

  "github.com/gin-contrib/logger"
  "github.com/gin-contrib/requestid"
  "github.com/gin-gonic/gin"
  "github.com/rs/zerolog"
  "github.com/rs/zerolog/log"
)

var rxURL = regexp.MustCompile(`^/regexp\d*`)

func main() {
  r := gin.New()

  // Add a logger middleware, which:
  //   - Logs all requests, like a combined access and error log.
  //   - Logs to stdout.
  // r.Use(logger.SetLogger())

  // Example pong request.
  r.GET("/pong", logger.SetLogger(), func(c *gin.Context) {
    c.String(http.StatusOK, "pong "+fmt.Sprint(time.Now().Unix()))
  })

  // Example ping request.
  r.GET("/ping", logger.SetLogger(
    logger.WithSkipPath([]string{"/skip"}),
    logger.WithUTC(true),
    logger.WithSkipPathRegexps(rxURL),
  ), func(c *gin.Context) {
    c.String(http.StatusOK, "pong "+fmt.Sprint(time.Now().Unix()))
  })

  // Example skip path request.
  r.GET("/skip", logger.SetLogger(
    logger.WithSkipPath([]string{"/skip"}),
  ), func(c *gin.Context) {
    c.String(http.StatusOK, "pong "+fmt.Sprint(time.Now().Unix()))
  })

  // Example skip path request.
  r.GET("/regexp1", logger.SetLogger(
    logger.WithSkipPathRegexps(rxURL),
  ), func(c *gin.Context) {
    c.String(http.StatusOK, "pong "+fmt.Sprint(time.Now().Unix()))
  })

  // Example skip path request.
  r.GET("/regexp2", logger.SetLogger(
    logger.WithSkipPathRegexps(rxURL),
  ), func(c *gin.Context) {
    c.String(http.StatusOK, "pong "+fmt.Sprint(time.Now().Unix()))
  })

  // add custom fields.
  r.GET("/id", requestid.New(requestid.WithGenerator(func() string {
    return "foobar"
  })), logger.SetLogger(
    logger.WithLogger(func(c *gin.Context, l zerolog.Logger) zerolog.Logger {
      if trace.SpanFromContext(c.Request.Context()).SpanContext().IsValid() {
        l = l.With().
          Str("trace_id", trace.SpanFromContext(c.Request.Context()).SpanContext().TraceID().String()).
          Str("span_id", trace.SpanFromContext(c.Request.Context()).SpanContext().SpanID().String()).
          Logger()
      }

      return l.With().
        Str("id", requestid.Get(c)).
        Str("foo", "bar").
        Str("path", c.Request.URL.Path).
        Logger()
    }),
  ), func(c *gin.Context) {
    c.String(http.StatusOK, "pong "+fmt.Sprint(time.Now().Unix()))
  })

  // Example of JSON format log
  r.GET("/json", logger.SetLogger(
    logger.WithLogger(func(_ *gin.Context, l zerolog.Logger) zerolog.Logger {
      return l.Output(gin.DefaultWriter).With().Logger()
    }),
  ), func(c *gin.Context) {
    c.String(http.StatusOK, "pong "+fmt.Sprint(time.Now().Unix()))
  })

  // Example of skipper usage
  r.GET("/health", logger.SetLogger(
    logger.WithSkipper(func(c *gin.Context) bool {
      return c.Request.URL.Path == "/health"
    }),
  ), func(c *gin.Context) {
    c.String(http.StatusOK, "pong "+fmt.Sprint(time.Now().Unix()))
  })

  // Example of skipper usage
  v1 := r.Group("/v1", logger.SetLogger(
    logger.WithSkipper(func(c *gin.Context) bool {
      return c.Request.Method == "GET"
    })))
  {
    v1.GET("/ping", func(c *gin.Context) {
      c.String(http.StatusOK, "pong01 "+fmt.Sprint(time.Now().Unix()))
    })
    v1.POST("/ping", func(c *gin.Context) {
      c.String(http.StatusOK, "pong02 "+fmt.Sprint(time.Now().Unix()))
    })
  }

  // Listen and Server in 0.0.0.0:8080
  if err := r.Run(":8080"); err != nil {
    log.Fatal().Msg("can' start server with 8080 port")
  }
}

Screenshot

Run app server:

go run _example/main.go

Test request:

curl http://localhost:8080/ping
curl http://localhost:8080/pong
curl http://localhost:8080/json

Documentation

Index

• func Get(c *gin.Context) zerolog.Logger
• func ParseLevel(levelStr string) (zerolog.Level, error)
• func SetLogger(opts ...Option) gin.HandlerFunc
• type Fn
• type Option
  • func WithClientErrorLevel(lvl zerolog.Level) Option
  • func WithDefaultLevel(lvl zerolog.Level) Option
  • func WithLogger(fn func(*gin.Context, zerolog.Logger) zerolog.Logger) Option
  • func WithPathLevel(m map[string]zerolog.Level) Option
  • func WithServerErrorLevel(lvl zerolog.Level) Option
  • func WithSkipPath(s []string) Option
  • func WithSkipPathRegexps(regs ...*regexp.Regexp) Option
  • func WithSkipper(s Skipper) Option
  • func WithUTC(s bool) Option
  • func WithWriter(s io.Writer) Option
• type Skipper

Functions

func Get

func Get(c *gin.Context) zerolog.Logger

Get retrieves the zerolog.Logger instance from the given gin.Context. It assumes that the logger has been previously set in the context with the key loggerKey. If the logger is not found, it will panic.

Parameters:

c - the gin.Context from which to retrieve the logger.

Returns:

zerolog.Logger - the logger instance stored in the context.

func ParseLevel

func ParseLevel(levelStr string) (zerolog.Level, error)

ParseLevel parses a string representation of a log level and returns the corresponding zerolog.Level. It takes a single argument:

• levelStr: a string representing the log level (e.g., "debug", "info", "warn", "error").

It returns:

• zerolog.Level: the parsed log level.
• error: an error if the log level string is invalid.

func SetLogger

func SetLogger(opts ...Option) gin.HandlerFunc

SetLogger returns a gin.HandlerFunc (middleware) that logs requests using zerolog. It accepts a variadic number of Option functions to customize the logger's behavior.

The logger configuration includes: - defaultLevel: the default logging level (default: zerolog.InfoLevel). - clientErrorLevel: the logging level for client errors (default: zerolog.WarnLevel). - serverErrorLevel: the logging level for server errors (default: zerolog.ErrorLevel). - output: the output writer for the logger (default: gin.DefaultWriter). - skipPath: a list of paths to skip logging. - skipPathRegexps: a list of regular expressions to skip logging for matching paths. - logger: a custom logger function to use instead of the default logger.

The middleware logs the following request details: - method: the HTTP method of the request. - path: the URL path of the request. - ip: the client's IP address. - user_agent: the User-Agent header of the request. - status: the HTTP status code of the response. - latency: the time taken to process the request. - body_size: the size of the response body.

The logging level for each request is determined based on the response status code: - clientErrorLevel for 4xx status codes. - serverErrorLevel for 5xx status codes. - defaultLevel for other status codes. - Custom levels can be set for specific paths using the pathLevels configuration.

Types

type Fn

type Fn func(*gin.Context, zerolog.Logger) zerolog.Logger

Fn is a function type that takes a gin.Context and a zerolog.Logger as parameters, and returns a zerolog.Logger. It is typically used to modify or enhance the logger within the context of a Gin HTTP request.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option specifies instrumentation configuration options.

func WithClientErrorLevel

func WithClientErrorLevel(lvl zerolog.Level) Option

WithClientErrorLevel set the log level used for request with status code between 400 and 499

func WithDefaultLevel

func WithDefaultLevel(lvl zerolog.Level) Option

WithDefaultLevel set the log level used for request with status code < 400

func WithLogger

func WithLogger(fn func(*gin.Context, zerolog.Logger) zerolog.Logger) Option

WithLogger set custom logger func

func WithPathLevel

func WithPathLevel(m map[string]zerolog.Level) Option

WithPathLevel use logging level for successful requests to a specific path

func WithServerErrorLevel

func WithServerErrorLevel(lvl zerolog.Level) Option

WithServerErrorLevel set the log level used for request with status code >= 500

func WithSkipPath

func WithSkipPath(s []string) Option

WithSkipPath skip URL path by specific pattern

func WithSkipPathRegexps

func WithSkipPathRegexps(regs ...*regexp.Regexp) Option

WithSkipPathRegexps multiple skip URL paths by regexp pattern

func WithSkipper

func WithSkipper(s Skipper) Option

WithSkipper returns an Option that sets the Skipper function in the config. The Skipper function determines whether a request should be skipped for logging.

Parameters:

s (Skipper): A function that takes a gin.Context and returns a boolean indicating
             whether the request should be skipped.

Returns:

Option: An option that sets the Skipper function in the config.

func WithUTC

func WithUTC(s bool) Option

WithUTC returns t with the location set to UTC.

func WithWriter

func WithWriter(s io.Writer) Option

WithWriter change the default output writer. Default is gin.DefaultWriter

type Skipper

type Skipper func(c *gin.Context) bool

Skipper defines a function to skip middleware. It takes a gin.Context as input and returns a boolean indicating whether to skip the middleware for the given context.