bunzerolog

README

bunzerolog

bunzerolog is a logging package for Bun that uses zerolog.
This package enables SQL queries executed by Bun to be logged and displayed using zerolog.

Installation

go get github.com/uptrace/bun/extra/bunzerolog

Features

• Supports setting a *zerolog.Logger instance or uses the global logger if not set.
• Supports setting a *zerolog.Logger instance using the context.
• Logs general SQL queries with configurable log levels.
• Logs slow SQL queries based on a configurable duration threshold.
• Logs SQL queries that result in errors, for easier debugging.
• Allows for custom log formatting.

Usage

First, import the bunzerolog package:

import "github.com/uptrace/bun/extra/bunzerolog"

Then, create a new QueryHook and add the hook to *bun.DB instance:

import "github.com/rs/zerolog"

db := bun.NewDB(sqldb, dialect)

hook := bunzerolog.NewQueryHook(
    bunzerolog.WithQueryLogLevel(zerolog.DebugLevel),
    bunzerolog.WithSlowQueryLogLevel(zerolog.WarnLevel),
    bunzerolog.WithErrorQueryLogLevel(zerolog.ErrorLevel),
    bunzerolog.WithSlowQueryThreshold(3 * time.Second),
)

db.AddQueryHook(hook)

Setting a Custom *zerolog.Logger Instance

To set a *zerolog.Logger instance, you can use the WithLogger option:

logger := zerolog.New(os.Stderr).With().Timestamp().Logger()
hook := bunzerolog.NewQueryHook(
    bunzerolog.WithLogger(logger),
	// other options...
)

If a *zerolog.Logger instance is not set, the logger from the context will be used.

Custom Log Formatting

To customize the log format, you can use the WithLogFormat option:

customFormat := func(ctx context.Context, event *bun.QueryEvent, zerevent *zerolog.Event) *zerolog.Event {
    duration := h.now().Sub(event.StartTime)
    
    return zerevent.
        Err(event.Err).
        Str("request_id", requestid.FromContext(ctx)).
        Str("query", event.Query).
        Str("operation", event.Operation()).
        Str("duration", duration.String())
}

hook := bunzerolog.NewQueryHook(
    bunzerolog.WithLogFormat(customFormat),
	// other options...
)

Options

• WithLogger(logger *zerolog.Logger): Sets a *zerolog.Logger instance. If not set, the logger from context will be used.
• WithQueryLogLevel(level zerolog.Level): Sets the log level for general queries.
• WithSlowQueryLogLevel(level zerolog.Level): Sets the log level for slow queries.
• WithErrorQueryLogLevel(level zerolog.Level): Sets the log level for queries that result in errors.
• WithSlowQueryThreshold(threshold time.Duration): Sets the duration threshold for identifying slow queries.
• WithLogFormat(f logFormat): Sets the custom format for slog output.

Documentation

Index

• type LogFormatFn
• type Option
  • func WithErrorQueryLogLevel(level zerolog.Level) Option
  • func WithLogFormat(f LogFormatFn) Option
  • func WithLogger(logger *zerolog.Logger) Option
  • func WithQueryLogLevel(level zerolog.Level) Option
  • func WithSlowQueryLogLevel(level zerolog.Level) Option
  • func WithSlowQueryThreshold(threshold time.Duration) Option
• type QueryHook
  • func NewQueryHook(opts ...Option) *QueryHook
  • func (h *QueryHook) AfterQuery(ctx context.Context, event *bun.QueryEvent)
  • func (h *QueryHook) BeforeQuery(ctx context.Context, event *bun.QueryEvent) context.Context

Types

type LogFormatFn

type LogFormatFn func(ctx context.Context, event *bun.QueryEvent, zeroctx *zerolog.Event) *zerolog.Event

type Option

type Option func(*QueryHook)

Option is a function that configures a QueryHook.

func WithErrorQueryLogLevel

func WithErrorQueryLogLevel(level zerolog.Level) Option

WithErrorQueryLogLevel sets the log level for queries that result in an error.

func WithLogFormat

func WithLogFormat(f LogFormatFn) Option

WithLogFormat sets the custom format for slog output.

func WithLogger

func WithLogger(logger *zerolog.Logger) Option

WithLogger sets the *zerolog.Logger instance.

func WithQueryLogLevel

func WithQueryLogLevel(level zerolog.Level) Option

WithQueryLogLevel sets the log level for general queries.

func WithSlowQueryLogLevel

func WithSlowQueryLogLevel(level zerolog.Level) Option

WithSlowQueryLogLevel sets the log level for slow queries.

func WithSlowQueryThreshold

func WithSlowQueryThreshold(threshold time.Duration) Option

WithSlowQueryThreshold sets the duration threshold for identifying slow queries.

type QueryHook

type QueryHook struct {
	// contains filtered or unexported fields
}

QueryHook is a hook for Bun that enables logging with slog. It implements bun.QueryHook interface.

func NewQueryHook

func NewQueryHook(opts ...Option) *QueryHook

NewQueryHook initializes a new QueryHook with the given options.

func (*QueryHook) AfterQuery

func (h *QueryHook) AfterQuery(ctx context.Context, event *bun.QueryEvent)

AfterQuery is called after a query is executed. It logs the query based on its duration and whether it resulted in an error.

func (*QueryHook) BeforeQuery

func (h *QueryHook) BeforeQuery(ctx context.Context, event *bun.QueryEvent) context.Context

BeforeQuery is called before a query is executed.