log

func AddContextAttrs ¶ added in v0.6.0

func AddContextAttrs(parent context.Context, logAttributes ...any) context.Context

AddContextAttrs returns a copy of the given parent context, with log attributes attached. When the context is passed to one of the log functions in this library, these attributes are added to the log output.

If AddContextAttrs has been called previously on the parent context (or any of its parents), then those attributes will be included as well. But if a previous context attribute has the same key as one of the new attributes, then the newer attribute overwrites the previous one in the returned context.

If you don't have an existing context when calling this, pass context.Background as the parent context.

Log attributes ¶

A log attribute (abbreviated "attr") is a key-value pair attached to a log line. You can pass attributes in the following ways:

// Pairs of string keys and corresponding values:
ctx = log.AddContextAttrs(ctx, "key1", "value1", "key2", 2)
// slog.Attr objects:
ctx = log.AddContextAttrs(ctx, slog.String("key1", "value1"), slog.Int("key2", 2))
// Or a mix of the two:
ctx = log.AddContextAttrs(ctx, "key1", "value1", slog.Int("key2", 2))

When outputting logs as JSON (using e.g. slog.JSONHandler), these become fields in the logged JSON object. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than if you were to just use string concatenation.

Attaching context attributes to errors ¶

Typically, when an error occurs, it is returned up the stack before being logged. This means that an error can escape its original context, and thus lose any context attributes that would otherwise be included in the log. To alleviate this, this library looks for the following method on logged errors:

Context() context.Context

If an error implements this method, then we include any attributes from the error's context in the log.

The hermannm.dev/wrap/ctxwrap package supports this use-case by providing error-wrapping functions that take a context.Context parameter.

Adding context attributes to logs made by log/slog ¶

When using AddContextAttrs, context attributes are added to the log output when you use the logging functions provided by this package. But you may have places in your application that use log/slog directly (such as an SDK that does request logging). To add context attributes to those logs as well, you can wrap your slog.Handler with log.ContextHandler, as follows:

logHandler := devlog.NewHandler(os.Stdout, nil) // Or any other Handler
slog.SetDefault(slog.New(log.ContextHandler(logHandler)))

Alternatively, you can use log.SetDefault, which applies log.ContextHandler for you:

log.SetDefault(devlog.NewHandler(os.Stdout, nil))

func ContextHandler ¶ added in v0.6.0

func ContextHandler(wrapped slog.Handler) slog.Handler

ContextHandler wraps a slog.Handler, adding context attributes from log.AddContextAttrs before forwarding logs to the wrapped handler.

The logging functions in this library already add context attributes. But logs made outside of this library (for example, a call to plain slog.InfoContext) won't add these attributes. That's why you may want to use this to wrap your slog.Handler, so that context attributes are added regardless of how the log is made (as long as a context.Context is passed to the logger).

Example of how to set up your handler with this:

logHandler := devlog.NewHandler(os.Stdout, nil)
slog.SetDefault(slog.New(log.ContextHandler(logHandler)))

Alternatively, you can use log.SetDefault, which applies log.ContextHandler for you:

log.SetDefault(devlog.NewHandler(os.Stdout, nil))

ContextHandler panics if the given handler is nil. If the handler is already wrapped by ContextHandler, then it's returned as-is.

func Debug ¶

func Debug(ctx context.Context, message string, logAttributes ...any)

Debug logs the given message at the DEBUG log level, along with any given log attributes. It uses the slog.Default logger.

Note that the DEBUG log level is typically disabled by default in most log handlers, in which case no output will be produced.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

Log attributes ¶

A log attribute (abbreviated "attr") is a key-value pair attached to a log line. You can pass attributes in the following ways:

// Pairs of string keys and corresponding values:
log.Debug(ctx, "Message", "key1", "value1", "key2", 2)
// slog.Attr objects:
log.Debug(ctx, "Message", slog.String("key1", "value1"), slog.Int("key2", 2))
// Or a mix of the two:
log.Debug(ctx, "Message", "key1", "value1", slog.Int("key2", 2))

When outputting logs as JSON (using e.g. slog.JSONHandler), these become fields in the logged JSON object. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than if you were to just use string concatenation.

func DebugError ¶ added in v0.5.0

func DebugError(ctx context.Context, err error, message string, logAttributes ...any)

DebugError logs the given message at the DEBUG log level, and adds a 'cause' attribute with the given error, along with any other given log attributes. It uses the slog.Default logger.

If you pass a blank string as the message, the error string is used as the log message.

Note that the DEBUG log level is typically disabled by default in most log handlers, in which case no output will be produced.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

Log attributes ¶

A log attribute (abbreviated "attr") is a key-value pair attached to a log line. You can pass attributes in the following ways:

// Pairs of string keys and corresponding values:
log.DebugError(ctx, err, "Message", "key1", "value1", "key2", 2)
// slog.Attr objects:
log.DebugError(ctx, err, "Message", slog.String("key1", "value1"), slog.Int("key2", 2))
// Or a mix of the two:
log.DebugError(ctx, err, "Message", "key1", "value1", slog.Int("key2", 2))

When outputting logs as JSON (using e.g. slog.JSONHandler), these become fields in the logged JSON object. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than if you were to just use string concatenation.

func DebugErrorf ¶ added in v0.6.0

func DebugErrorf(ctx context.Context, err error, messageFormat string, formatArgs ...any)

DebugErrorf logs a formatted message (using fmt.Sprintf) at the DEBUG log level, and adds a 'cause' attribute with the given error. It uses the slog.Default logger.

Note that the DEBUG log level is typically disabled by default in most log handlers, in which case no output will be produced.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

If you have structured data to attach to the log, you should use log.DebugError instead, with log attributes instead of format args. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than arbitrary message formatting. If you want both attributes and a formatted message, you should call log.DebugError and format the message directly with fmt.Sprintf.

func DebugErrors ¶ added in v0.5.0

func DebugErrors(ctx context.Context, errors []error, message string, logAttributes ...any)

DebugErrors logs the given message at the DEBUG log level, and adds a 'cause' attribute with the given errors, along with any other given log attributes. It uses the slog.Default logger.

Note that the DEBUG log level is typically disabled by default in most log handlers, in which case no output will be produced.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

Log attributes ¶

A log attribute (abbreviated "attr") is a key-value pair attached to a log line. You can pass attributes in the following ways:

// Pairs of string keys and corresponding values:
log.DebugErrors(ctx, errs, "Message", "key1", "value1", "key2", 2)
// slog.Attr objects:
log.DebugErrors(ctx, errs, "Message", slog.String("key1", "value1"), slog.Int("key2", 2))
// Or a mix of the two:
log.DebugErrors(ctx, errs, "Message", "key1", "value1", slog.Int("key2", 2))

When outputting logs as JSON (using e.g. slog.JSONHandler), these become fields in the logged JSON object. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than if you were to just use string concatenation.

func DebugErrorsf ¶ added in v0.6.0

func DebugErrorsf(ctx context.Context, errors []error, messageFormat string, formatArgs ...any)

DebugErrorsf logs a formatted message (using fmt.Sprintf) at the DEBUG log level, and adds a 'cause' attribute with the given errors. It uses the slog.Default logger.

Note that the DEBUG log level is typically disabled by default in most log handlers, in which case no output will be produced.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

If you have structured data to attach to the log, you should use log.DebugErrors instead, with log attributes instead of format args. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than arbitrary message formatting. If you want both attributes and a formatted message, you should call log.DebugErrors and format the message directly with fmt.Sprintf.

func Debugf ¶

func Debugf(ctx context.Context, messageFormat string, formatArgs ...any)

Debugf creates a message from the given format string and arguments using fmt.Sprintf, and logs it at the DEBUG log level. It uses the slog.Default logger.

Note that the DEBUG log level is typically disabled by default in most log handlers, in which case no output will be produced.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

If you have structured data to attach to the log, you should use log.Debug instead, with log attributes instead of format args. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than arbitrary message formatting. If you want both attributes and a formatted message, you should call log.Debug and format the message directly with fmt.Sprintf.

func Enabled ¶ added in v0.6.0

func Enabled(ctx context.Context, level slog.Level) bool

Enabled returns true if log output is enabled for the given log level in the default logger's handler.

The logging functions in this package already check this before outputting logs (and before performing any message formatting), so you don't have to check this if you're just making a normal log. But if you're constructing some expensive value for the log, you can use this to check if the level is enabled before paying that cost.

The context parameter may be used by the log handler to determine whether the level is enabled. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

func Error ¶

func Error(ctx context.Context, err error, message string, logAttributes ...any)

Error logs the given message at the ERROR log level, and adds a 'cause' attribute with the given error, along with any other given log attributes. It uses the slog.Default logger.

If you pass a blank string as the message, the error string is used as the log message.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

Log attributes ¶

A log attribute (abbreviated "attr") is a key-value pair attached to a log line. You can pass attributes in the following ways:

// Pairs of string keys and corresponding values:
log.Error(ctx, err, "Message", "key1", "value1", "key2", 2)
// slog.Attr objects:
log.Error(ctx, err, "Message", slog.String("key1", "value1"), slog.Int("key2", 2))
// Or a mix of the two:
log.Error(ctx, err, "Message", "key1", "value1", slog.Int("key2", 2))

When outputting logs as JSON (using e.g. slog.JSONHandler), these become fields in the logged JSON object. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than if you were to just use string concatenation.

func ErrorMessage ¶

func ErrorMessage(ctx context.Context, message string, logAttributes ...any)

ErrorMessage logs the given message at the ERROR log level, along with any given log attributes. It uses the slog.Default logger.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

Log attributes ¶

A log attribute (abbreviated "attr") is a key-value pair attached to a log line. You can pass attributes in the following ways:

// Pairs of string keys and corresponding values:
log.ErrorMessage(ctx, "Message", "key1", "value1", "key2", 2)
// slog.Attr objects:
log.ErrorMessage(ctx, "Message", slog.String("key1", "value1"), slog.Int("key2", 2))
// Or a mix of the two:
log.ErrorMessage(ctx, "Message", "key1", "value1", slog.Int("key2", 2))

When outputting logs as JSON (using e.g. slog.JSONHandler), these become fields in the logged JSON object. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than if you were to just use string concatenation.

func ErrorMessagef ¶

func ErrorMessagef(ctx context.Context, messageFormat string, formatArgs ...any)

ErrorMessagef creates a message from the given format string and arguments using fmt.Sprintf, and logs it at the ERROR log level. It uses the slog.Default logger.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

If you have structured data to attach to the log, you should use log.ErrorMessage instead, with log attributes instead of format args. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than arbitrary message formatting. If you want both attributes and a formatted message, you should call log.ErrorMessage and format the message directly with fmt.Sprintf.

func Errorf ¶

func Errorf(ctx context.Context, err error, messageFormat string, formatArgs ...any)

Errorf logs a formatted message (using fmt.Sprintf) at the ERROR log level, and adds a 'cause' attribute with the given error. It uses the slog.Default logger.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

If you have structured data to attach to the log, you should use log.Error instead, with log attributes instead of format args. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than arbitrary message formatting. If you want both attributes and a formatted message, you should call log.Error and format the message directly with fmt.Sprintf.

func Errors ¶

func Errors(ctx context.Context, errors []error, message string, logAttributes ...any)

Errors logs the given message at the ERROR log level, and adds a 'cause' attribute with the given errors, along with any other given log attributes. It uses the slog.Default logger.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

Log attributes ¶

A log attribute (abbreviated "attr") is a key-value pair attached to a log line. You can pass attributes in the following ways:

// Pairs of string keys and corresponding values:
log.Errors(ctx, errs, "Message", "key1", "value1", "key2", 2)
// slog.Attr objects:
log.Errors(ctx, errs, "Message", slog.String("key1", "value1"), slog.Int("key2", 2))
// Or a mix of the two:
log.Errors(ctx, errs, "Message", "key1", "value1", slog.Int("key2", 2))

When outputting logs as JSON (using e.g. slog.JSONHandler), these become fields in the logged JSON object. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than if you were to just use string concatenation.

func Errorsf ¶ added in v0.6.0

func Errorsf(ctx context.Context, errors []error, messageFormat string, formatArgs ...any)

Errorsf logs a formatted message (using fmt.Sprintf) at the ERROR log level, and adds a 'cause' attribute with the given errors. It uses the slog.Default logger.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

If you have structured data to attach to the log, you should use log.Errors instead, with log attributes instead of format args. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than arbitrary message formatting. If you want both attributes and a formatted message, you should call log.Errors and format the message directly with fmt.Sprintf.

func Info ¶

func Info(ctx context.Context, message string, logAttributes ...any)

Info logs the given message at the INFO log level, along with any given log attributes. It uses the slog.Default logger.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

Log attributes ¶

A log attribute (abbreviated "attr") is a key-value pair attached to a log line. You can pass attributes in the following ways:

// Pairs of string keys and corresponding values:
log.Info(ctx, "Message", "key1", "value1", "key2", 2)
// slog.Attr objects:
log.Info(ctx, "Message", slog.String("key1", "value1"), slog.Int("key2", 2))
// Or a mix of the two:
log.Info(ctx, "Message", "key1", "value1", slog.Int("key2", 2))

When outputting logs as JSON (using e.g. slog.JSONHandler), these become fields in the logged JSON object. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than if you were to just use string concatenation.

func InfoError ¶ added in v0.6.0

func InfoError(ctx context.Context, err error, message string, logAttributes ...any)

InfoError logs the given message at the INFO log level, and adds a 'cause' attribute with the given error, along with any other given log attributes. It uses the slog.Default logger.

If you pass a blank string as the message, the error string is used as the log message.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

Log attributes ¶

A log attribute (abbreviated "attr") is a key-value pair attached to a log line. You can pass attributes in the following ways:

// Pairs of string keys and corresponding values:
log.InfoError(ctx, err, "Message", "key1", "value1", "key2", 2)
// slog.Attr objects:
log.InfoError(ctx, err, "Message", slog.String("key1", "value1"), slog.Int("key2", 2))
// Or a mix of the two:
log.InfoError(ctx, err, "Message", "key1", "value1", slog.Int("key2", 2))

When outputting logs as JSON (using e.g. slog.JSONHandler), these become fields in the logged JSON object. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than if you were to just use string concatenation.

func InfoErrorf ¶ added in v0.6.0

func InfoErrorf(ctx context.Context, err error, messageFormat string, formatArgs ...any)

InfoErrorf logs a formatted message (using fmt.Sprintf) at the INFO log level, and adds a 'cause' attribute with the given error. It uses the slog.Default logger.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

If you have structured data to attach to the log, you should use log.InfoError instead, with log attributes instead of format args. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than arbitrary message formatting. If you want both attributes and a formatted message, you should call log.InfoError and format the message directly with fmt.Sprintf.

func InfoErrors ¶ added in v0.6.0

func InfoErrors(ctx context.Context, errors []error, message string, logAttributes ...any)

InfoErrors logs the given message at the INFO log level, and adds a 'cause' attribute with the given errors, along with any other given log attributes. It uses the slog.Default logger.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

Log attributes ¶

A log attribute (abbreviated "attr") is a key-value pair attached to a log line. You can pass attributes in the following ways:

// Pairs of string keys and corresponding values:
log.InfoErrors(ctx, errs, "Message", "key1", "value1", "key2", 2)
// slog.Attr objects:
log.InfoErrors(ctx, errs, "Message", slog.String("key1", "value1"), slog.Int("key2", 2))
// Or a mix of the two:
log.InfoErrors(ctx, errs, "Message", "key1", "value1", slog.Int("key2", 2))

When outputting logs as JSON (using e.g. slog.JSONHandler), these become fields in the logged JSON object. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than if you were to just use string concatenation.

func InfoErrorsf ¶ added in v0.6.0

func InfoErrorsf(ctx context.Context, errors []error, messageFormat string, formatArgs ...any)

InfoErrorsf logs a formatted message (using fmt.Sprintf) at the INFO log level, and adds a 'cause' attribute with the given errors. It uses the slog.Default logger.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

If you have structured data to attach to the log, you should use log.InfoErrors instead, with log attributes instead of format args. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than arbitrary message formatting. If you want both attributes and a formatted message, you should call log.InfoErrors and format the message directly with fmt.Sprintf.

func Infof ¶

func Infof(ctx context.Context, messageFormat string, formatArgs ...any)

Infof creates a message from the given format string and arguments using fmt.Sprintf, and logs it at the INFO log level. It uses the slog.Default logger.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

If you have structured data to attach to the log, you should use log.Info instead, with log attributes instead of format args. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than arbitrary message formatting. If you want both attributes and a formatted message, you should call log.Info and format the message directly with fmt.Sprintf.

func Log ¶ added in v0.6.0

func Log(ctx context.Context, level slog.Level, message string, logAttributes ...any)

Log logs a message at the given log level, along with any given log attributes. It uses the slog.Default logger.

This function lets you set the log level dynamically. If you just want to log at a specific level, you should use a more specific log function (log.Info, log.Warn, etc.) instead.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

Log attributes ¶

A log attribute (abbreviated "attr") is a key-value pair attached to a log line. You can pass attributes in the following ways:

// Pairs of string keys and corresponding values:
log.Log(ctx, level, "Message", "key1", "value1", "key2", 2)
// slog.Attr objects:
log.Log(ctx, level, "Message", slog.String("key1", "value1"), slog.Int("key2", 2))
// Or a mix of the two:
log.Log(ctx, level, "Message", "key1", "value1", slog.Int("key2", 2))

When outputting logs as JSON (using e.g. slog.JSONHandler), these become fields in the logged JSON object. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than if you were to just use string concatenation.

func LogWithError ¶ added in v0.6.0

func LogWithError(
	ctx context.Context,
	level slog.Level,
	err error,
	message string,
	logAttributes ...any,
)

LogWithError logs a message at the given log level, and adds a 'cause' attribute with the given error, along with any other given log attributes. It uses the slog.Default logger.

This function lets you set the log level dynamically. If you just want to log at a specific level, you should use a more specific log function (log.Error, log.WarnError, etc.) instead.

If you pass a blank string as the message, the error string is used as the log message.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

Log attributes ¶

A log attribute (abbreviated "attr") is a key-value pair attached to a log line. You can pass attributes in the following ways:

// Pairs of string keys and corresponding values:
log.LogWithError(ctx, level, err, "Message", "key1", "value1", "key2", 2)
// slog.Attr objects:
log.LogWithError(ctx, level, err, "Message", slog.String("key1", "value1"), slog.Int("key2", 2))
// Or a mix of the two:
log.LogWithError(ctx, level, err, "Message", "key1", "value1", slog.Int("key2", 2))

When outputting logs as JSON (using e.g. slog.JSONHandler), these become fields in the logged JSON object. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than if you were to just use string concatenation.

func LogWithErrorf ¶ added in v0.6.0

func LogWithErrorf(
	ctx context.Context,
	level slog.Level,
	err error,
	messageFormat string,
	formatArgs ...any,
)

LogWithErrorf logs a formatted message (using fmt.Sprintf) at the given log level, and adds a 'cause' attribute with the given error. It uses the slog.Default logger.

This function lets you set the log level dynamically. If you just want to log at a specific level, you should use a more specific log function (log.Errorf, log.WarnErrorf, etc.) instead.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

If you have structured data to attach to the log, you should use log.LogWithError instead, with log attributes instead of format args. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than arbitrary message formatting. If you want both attributes and a formatted message, you should call log.LogWithError and format the message directly with fmt.Sprintf.

func LogWithErrors ¶ added in v0.6.0

func LogWithErrors(
	ctx context.Context,
	level slog.Level,
	errors []error,
	message string,
	logAttributes ...any,
)

LogWithErrors logs a message at the given log level, and adds a 'cause' attribute with the given errors, along with any other given log attributes. It uses the slog.Default logger.

This function lets you set the log level dynamically. If you just want to log at a specific level, you should use a more specific log function (log.Errors, log.WarnErrors, etc.) instead.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

Log attributes ¶

A log attribute (abbreviated "attr") is a key-value pair attached to a log line. You can pass attributes in the following ways:

// Pairs of string keys and corresponding values:
log.LogWithErrors(ctx, level, errs, "Message", "key1", "value1", "key2", 2)
// slog.Attr objects:
log.LogWithErrors(ctx, level, errs, "Message", slog.String("key1", "value1"), slog.Int("key2", 2))
// Or a mix of the two:
log.LogWithErrors(ctx, level, errs, "Message", "key1", "value1", slog.Int("key2", 2))

When outputting logs as JSON (using e.g. slog.JSONHandler), these become fields in the logged JSON object. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than if you were to just use string concatenation.

func LogWithErrorsf ¶ added in v0.6.0

func LogWithErrorsf(
	ctx context.Context,
	level slog.Level,
	errors []error,
	messageFormat string,
	formatArgs ...any,
)

LogWithErrorsf logs a formatted message (using fmt.Sprintf) at the given log level, and adds a 'cause' attribute with the given errors. It uses the slog.Default logger.

This function lets you set the log level dynamically. If you just want to log at a specific level, you should use a more specific log function (log.Errorsf, log.WarnErrorsf, etc.) instead.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

If you have structured data to attach to the log, you should use log.LogWithErrors instead, with log attributes instead of format args. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than arbitrary message formatting. If you want both attributes and a formatted message, you should call log.LogWithErrors and format the message directly with fmt.Sprintf.

func Logf ¶ added in v0.6.0

func Logf(ctx context.Context, level slog.Level, messageFormat string, formatArgs ...any)

Logf creates a message from the given format string and arguments using fmt.Sprintf, and logs it at the given log level. It uses the slog.Default logger.

This function lets you set the log level dynamically. If you just want to log at a specific level, you should use a more specific log function (log.Infof, log.Warnf, etc.) instead.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

If you have structured data to attach to the log, you should use log.Log instead, with log attributes instead of format args. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than arbitrary message formatting. If you want both attributes and a formatted message, you should call log.Log and format the message directly with fmt.Sprintf.

func SetDefault ¶ added in v0.6.0

func SetDefault(logHandler slog.Handler)

SetDefault is short-hand for calling:

slog.SetDefault(slog.New(log.ContextHandler(logHandler)))

The handler is wrapped with log.ContextHandler (unless it's already wrapped), so that context attributes from log.AddContextAttrs are also added to logs made outside of this library.

SetDefault panics if the given handler is nil.

func Warn ¶

func Warn(ctx context.Context, message string, logAttributes ...any)

Warn logs the given message at the WARN log level, along with any given log attributes. It uses the slog.Default logger.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

Log attributes ¶

A log attribute (abbreviated "attr") is a key-value pair attached to a log line. You can pass attributes in the following ways:

// Pairs of string keys and corresponding values:
log.Warn(ctx, "Message", "key1", "value1", "key2", 2)
// slog.Attr objects:
log.Warn(ctx, "Message", slog.String("key1", "value1"), slog.Int("key2", 2))
// Or a mix of the two:
log.Warn(ctx, "Message", "key1", "value1", slog.Int("key2", 2))

When outputting logs as JSON (using e.g. slog.JSONHandler), these become fields in the logged JSON object. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than if you were to just use string concatenation.

func WarnError ¶

func WarnError(ctx context.Context, err error, message string, logAttributes ...any)

WarnError logs the given message at the WARN log level, and adds a 'cause' attribute with the given error, along with any other given log attributes. It uses the slog.Default logger.

If you pass a blank string as the message, the error string is used as the log message.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

Log attributes ¶

A log attribute (abbreviated "attr") is a key-value pair attached to a log line. You can pass attributes in the following ways:

// Pairs of string keys and corresponding values:
log.WarnError(ctx, err, "Message", "key1", "value1", "key2", 2)
// slog.Attr objects:
log.WarnError(ctx, err, "Message", slog.String("key1", "value1"), slog.Int("key2", 2))
// Or a mix of the two:
log.WarnError(ctx, err, "Message", "key1", "value1", slog.Int("key2", 2))

When outputting logs as JSON (using e.g. slog.JSONHandler), these become fields in the logged JSON object. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than if you were to just use string concatenation.

func WarnErrorf ¶

func WarnErrorf(ctx context.Context, err error, messageFormat string, formatArgs ...any)

WarnErrorf logs a formatted message (using fmt.Sprintf) at the WARN log level, and adds a 'cause' attribute with the given error. It uses the slog.Default logger.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

If you have structured data to attach to the log, you should use log.WarnError instead, with log attributes instead of format args. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than arbitrary message formatting. If you want both attributes and a formatted message, you should call log.WarnError and format the message directly with fmt.Sprintf.

func WarnErrors ¶

func WarnErrors(ctx context.Context, errors []error, message string, logAttributes ...any)

WarnErrors logs the given message at the WARN log level, and adds a 'cause' attribute with the given errors, along with any other given log attributes. It uses the slog.Default logger.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

Log attributes ¶

A log attribute (abbreviated "attr") is a key-value pair attached to a log line. You can pass attributes in the following ways:

// Pairs of string keys and corresponding values:
log.WarnErrors(ctx, errs, "Message", "key1", "value1", "key2", 2)
// slog.Attr objects:
log.WarnErrors(ctx, errs, "Message", slog.String("key1", "value1"), slog.Int("key2", 2))
// Or a mix of the two:
log.WarnErrors(ctx, errs, "Message", "key1", "value1", slog.Int("key2", 2))

When outputting logs as JSON (using e.g. slog.JSONHandler), these become fields in the logged JSON object. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than if you were to just use string concatenation.

func WarnErrorsf ¶ added in v0.6.0

func WarnErrorsf(ctx context.Context, errors []error, messageFormat string, formatArgs ...any)

WarnErrorsf logs a formatted message (using fmt.Sprintf) at the WARN log level, and adds a 'cause' attribute with the given errors. It uses the slog.Default logger.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

If you have structured data to attach to the log, you should use log.WarnErrors instead, with log attributes instead of format args. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than arbitrary message formatting. If you want both attributes and a formatted message, you should call log.WarnErrors and format the message directly with fmt.Sprintf.

func Warnf ¶

func Warnf(ctx context.Context, messageFormat string, formatArgs ...any)

Warnf creates a message from the given format string and arguments using fmt.Sprintf, and logs it at the WARN log level. It uses the slog.Default logger.

The context parameter is used to add context attributes from log.AddContextAttrs. If you're in a function without a context parameter, you may pass a nil context. But ideally, you should pass a context wherever you do logging, in order to propagate context attributes.

If you have structured data to attach to the log, you should use log.Warn instead, with log attributes instead of format args. This allows you to filter and query on the attributes in the log analysis tool of your choice, in a more structured manner than arbitrary message formatting. If you want both attributes and a formatted message, you should call log.Warn and format the message directly with fmt.Sprintf.