diff --git a/logger.go b/logger.go index 1736130..0aa5a22 100644 --- a/logger.go +++ b/logger.go @@ -12,31 +12,36 @@ import ( "github.com/rs/zerolog" ) +// 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 Fn func(*gin.Context, zerolog.Logger) zerolog.Logger -// Skipper is a function to skip logs based on provided Context +// 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. type Skipper func(c *gin.Context) bool -// Config defines the config for logger middleware +// config holds the configuration for the logger middleware. type config struct { + // logger is a function that defines the logging behavior. logger Fn - // UTC a boolean stating whether to use UTC time zone or local. - utc bool - skipPath []string + // utc is a boolean stating whether to use UTC time zone or local. + utc bool + // skipPath is a list of paths to be skipped from logging. + skipPath []string + // skipPathRegexps is a list of regular expressions to match paths to be skipped from logging. skipPathRegexps []*regexp.Regexp - // skip is a Skipper that indicates which logs should not be written. - // Optional. + // skip is a Skipper that indicates which logs should not be written. Optional. skip Skipper - // Output is a writer where logs are written. - // Optional. Default value is gin.DefaultWriter. + // output is a writer where logs are written. Optional. Default value is gin.DefaultWriter. output io.Writer - // the log level used for request with status code < 400 + // defaultLevel is the log level used for requests with status code < 400. defaultLevel zerolog.Level - // the log level used for request with status code between 400 and 499 + // clientErrorLevel is the log level used for requests with status code between 400 and 499. clientErrorLevel zerolog.Level - // the log level used for request with status code >= 500 + // serverErrorLevel is the log level used for requests with status code >= 500. serverErrorLevel zerolog.Level - // the log level to use for a specific path with status code < 400 + // pathLevels is a map of specific paths to log levels for requests with status code < 400. pathLevels map[string]zerolog.Level } @@ -44,7 +49,32 @@ const loggerKey = "_gin-contrib/logger_" var isTerm bool = isatty.IsTerminal(os.Stdout.Fd()) -// SetLogger initializes the logging middleware. +// 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. func SetLogger(opts ...Option) gin.HandlerFunc { cfg := &config{ defaultLevel: zerolog.InfoLevel, @@ -156,13 +186,28 @@ func SetLogger(opts ...Option) gin.HandlerFunc { } } -// ParseLevel converts a level string into a zerolog Level value. -// returns an error if the input string does not match known values. +// 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 ParseLevel(levelStr string) (zerolog.Level, error) { return zerolog.ParseLevel(levelStr) } -// Get return the logger associated with a gin context +// 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 Get(c *gin.Context) zerolog.Logger { return c.MustGet(loggerKey).(zerolog.Logger) }