bunslog

README

bunslog

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

Installation

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

Features

• Supports setting a *slog.Logger instance or uses the global logger if not set.
• 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 bunslog package:

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

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

db := bun.NewDB(sqldb, dialect)

hook := bunslog.NewQueryHook(
	bunslog.WithQueryLogLevel(slog.LevelDebug),
	bunslog.WithSlowQueryLogLevel(slog.LevelWarn),
	bunslog.WithErrorQueryLogLevel(slog.LevelError),
	bunslog.WithSlowQueryThreshold(3 * time.Second),
)

db.AddQueryHook(hook)

Setting a Custom *slog.Logger Instance

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

logger := slog.NewLogger()
hook := bunslog.NewQueryHook(
	bunslog.WithLogger(logger),
	// other options...
)

If a *slog.Logger instance is not set, the global logger will be used.

Custom Log Formatting

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

customFormat := func(event *bun.QueryEvent) []slog.Attr {
	// your custom formatting logic here
}

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

Options

• WithLogger(logger *slog.Logger): Sets a *slog.Logger instance. If not set, the global logger will be used.
• WithQueryLogLevel(level slog.Level): Sets the log level for general queries.
• WithSlowQueryLogLevel(level slog.Level): Sets the log level for slow queries.
• WithErrorQueryLogLevel(level slog.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 Option
  • func WithErrorQueryLogLevel(level slog.Level) Option
  • func WithLogFormat(f logFormat) Option
  • func WithLogger(logger *slog.Logger) Option
  • func WithQueryLogLevel(level slog.Level) Option
  • func WithSlowQueryLogLevel(level slog.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 Option

type Option func(*QueryHook)

Option is a function that configures a QueryHook.

func WithErrorQueryLogLevel

func WithErrorQueryLogLevel(level slog.Level) Option

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

func WithLogFormat

func WithLogFormat(f logFormat) Option

WithLogFormat sets the custom format for slog output.

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger sets the *slog.Logger instance.

func WithQueryLogLevel

func WithQueryLogLevel(level slog.Level) Option

WithQueryLogLevel sets the log level for general queries.

func WithSlowQueryLogLevel

func WithSlowQueryLogLevel(level slog.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.