flume

func AbbreviateLevel ¶

func AbbreviateLevel(_ []string, attr slog.Attr) slog.Attr

AbbreviateLevel is a ReplaceAttr function that abbreviates log level names.

It modifies the attribute if it's a log level (slog.Level) and changes the level name to its abbreviation. The abbreviations are:

• "DEBUG" becomes "DBG"
• "INFO" becomes "INF"
• "WARN" becomes "WRN"
• "ERROR" becomes "ERR"

If the attribute's value is not a slog.Level, it is returned unchanged.

Example:

// Create a logger with the ReplaceAttr function.
logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
	ReplaceAttr: AbbreviateLevel,
}))

// Log a message.
logger.Debug("This is a debug message.") // Output will be: level=DBG msg="This is a debug message."

func ChainReplaceAttrs ¶

func ChainReplaceAttrs(fns ...func([]string, slog.Attr) slog.Attr) func([]string, slog.Attr) slog.Attr

ChainReplaceAttrs composes a series of ReplaceAttr functions into a single ReplaceAttr function.

func ConfigFromEnv ¶

func ConfigFromEnv(envvars ...string) error

ConfigFromEnv configures flume from environment variables. It should be called from main():

func main() {
    flume.ConfigFromEnv()
    ...
 }

It searches envvars for the first environment variable that is set, and attempts to parse the value.

If no environment variable is set, it silently does nothing.

If an environment variable with a value is found, but parsing fails, an error is returned.

If envvars is empty, it defaults to DefaultConfigEnvVars.

func DetailedErrors ¶

func DetailedErrors(_ []string, a slog.Attr) slog.Attr

DetailedErrors is a ReplaceAttr function which ensures that errors implement fmt.Formatter are rendered the same by the JSONHandler as by the TextHandler. By default, the slog.JSONHandler renders errors as err.Error(), where as the slog.TextHandler will render it with fmt.Sprintf("%+v", err).

When using DetailedErrors, if any error values implement fmt.Formatter ( and therefore *may* implement some form of detailed error printing), and *do not* already implement json.Marshaler, then the value is wrapped in an error implementation which implements json.Marshaler, and marshals the error to a string using fmt.Sprintf("%+v", err).

func FixedTime ¶

func FixedTime(t time.Time) func(_ []string, a slog.Attr) slog.Attr

FixedTime replaces all time attributes with a fixed value. Useful in testing to get a predictable log line.

func FormatTimes ¶

func FormatTimes(format string) func([]string, slog.Attr) slog.Attr

FormatTimes returns a ReplaceAttr function that formats time values according to the specified format.

It modifies an attribute if its value is a time.Time. The time is formatted using the provided format string, and the attribute's value is updated to the formatted time string.

If the attribute's value is not a time.Time, it is returned unchanged.

Args:

format string: The format string to use for formatting time values (e.g., time.DateTime, "2006-01-02", "15:04:05").

Returns:

func([]string, slog.Attr) slog.Attr: A ReplaceAttr function that formats time values.

Example:

	// Create a ReplaceAttr function that formats times using a custom format.
	customTimeFormat := FormatTimes("2006-01-02 15:04:05")

	// Create a logger with the ReplaceAttr function.
	logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
	    ReplaceAttr: customTimeFormat,
	}))

	// Log a message with a time attribute.
	logger.Info("Time example", slog.Time("now", time.Now()))
	// Output might be: level=INFO msg="Time example" now="2023-10-27 10:30:00"

 // Create a ReplaceAttr function that formats times using a predefined format.
 dateTimeFormat := FormatTimes(time.DateTime)

 // Create a logger with the ReplaceAttr function.
 logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
     ReplaceAttr: dateTimeFormat,
 }))

 // Log a message with a time attribute.
 logger.Info("Time example", slog.Time("now", time.Now()))
 // Output might be: level=INFO msg="Time example" now="2023-10-27 10:30:00.000"

func ISO8601Time ¶

func ISO8601Time() func([]string, slog.Attr) slog.Attr

ISO8601Time returns a ReplaceAttr function that formats time to the ISO8601 compliant format used by flumev1 and zap. It is here to provide backward compatibility with flume v1, but should probably be avoided for new applications, in favor of the default formatting selected by the handler. The json and text handlers in the slog package use RFC3339, which is mostly compatible with ISO8601 anyway (see https://ijmacd.github.io/rfc3339-iso8601/ for how they overlap).

func LogFuncWriter ¶

func LogFuncWriter(l func(args ...any), trimSpace bool) io.Writer

LogFuncWriter is a writer which writes to a logging function signature like that of testing.T.Log() and fmt/log.Println(). It can be used to redirect slog output (or any other line-oriented logging output) to some other logging function.

SetOut(LogFuncWriter(fmt.Println, true))
SetOut(LogFuncWriter(t.Log, true))

func LoggerFuncWriter ¶

func LoggerFuncWriter(l func(msg string, kvpairs ...any)) io.Writer

LoggerFuncWriter is a writer which writes to functions with a signature like slog.Logger's logging functions, like slog.Logger.Info(), slog.Logger.Debug(), and slog.Logger.Error(). It can be used to adapt libraries which expect a logging function to slog.Logger.

http.Server{
    ErrorLog: log.New(LoggerFuncWriter(flume.New("http").Error), "", 0),
}

func MustConfigFromEnv ¶

func MustConfigFromEnv(envvars ...string)

MustConfigFromEnv is like ConfigFromEnv, but panics on error.

func New ¶

func New(name string) *slog.Logger

New is a convenience for creating a named logger using the default handler.

These package-level functions are typically used to initialize package-level loggers in var initializers, which can later be configured in main(). See [Controller.Logger]

Example:

package http
var logger = flume.New("http")

ogOpts := Default().HandlerOptions()
defer Default().SetHandlerOptions(ogOpts)

// The default handler is a noop handler that discards all log messages.
// To enable logging, using a default slog text handler writing to os.Stdout,
// call Default().SetHandlerOptions(nil)
Default().SetHandlerOptions(nil)

// This creates a named logger with the name "my-app", using the default handler.
log := New("my-app")
log.Info("Hello, World!")

// Output will be something like:
// time=2025-02-26T09:47:59.129-06:00 level=INFO msg="Hello, World!" logger=my-app

func RFC3339MillisTime ¶

func RFC3339MillisTime() func(_ []string, a slog.Attr) slog.Attr

RFC3339MillisTime returns a ReplaceAttr function which formats time to the format that slog's text handler uses.

func RegisterHandlerFn ¶

func RegisterHandlerFn(name string, fn HandlerFn)

RegisterHandlerFn registers a handler with a name. The handler can be looked up with LookupHandlerFn. If a handler function was already registered with the given name, the old handler function is replaced. Built-in handler functions can also be replaced in this manner.

func SecondsDuration ¶

func SecondsDuration() func(_ []string, a slog.Attr) slog.Attr

SecondsDuration formats durations as fractional seconds. This may be used to mimic the default encoding of durations in flumev1/zap.

func SimpleTime ¶

func SimpleTime() func([]string, slog.Attr) slog.Attr

SimpleTime returns a ReplaceAttr function that formats time values to a simple time format: "15:04:05.000".

It's a convenience function that uses FormatTimes internally with a predefined format.

Example:

// Create a logger with the ReplaceAttr function.
logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
    ReplaceAttr: SimpleTime(),
}))

// Log a message with a time attribute.
logger.Info("Time example", slog.Time("now", time.Now()))
// Output might be: level=INFO msg="Time example" now="10:30:00.000"

func UnmarshalEnv ¶

func UnmarshalEnv(o *HandlerOptions, envvars ...string) error

UnmarshalEnv reads handler options from an environment variable. The first environment variable in the list with a non-empty value will be unmarshaled into the options arg.

The first argument must not be nil.

The value of the environment variable can be either json, or a levels string:

FLUME={"level":"inf"}            // json
FLUME=*=inf                      // levels string

This is the full schema for the json encoding:

{
  "development": <bool>,
  "handler": <str>,       // looks up HandlerFn using LookupHandlerFn()
  "encoding": <str>,      // v1 alias for "handler"; if both set, "handler" wins
  "level": <str>,         // e.g. "INF", "INFO", "INF-1"
  "levels": <str or obj>, // either a levels string, or an object where the keys
                          // are logger names, and the values are levels (in the same
                          // format as the "level" property)
  "addSource": <bool>,
  "addCaller": <bool>,    // v1 alias for "addSource"; if both set, "addSource" wins
}

Level strings are in the form:

	 Levels    = Directive {"," Directive} .
  Directive = logger | "-" logger | logger "=" Level | "*" .
  Level     = LevelName [ "-" offset ] | int .
  LevelName = "DEBUG" | "DBG" | "INFO" | "INF" |
              "WARN" | "WRN" | "ERROR" | "ERR" |
              "ALL" | "OFF" | ""

Where `logger` is the name of a logger. "*" sets the default level. LevelName is case-insensitive.

Example:

*=INF,http,-sql,boot=DEBUG,authz=ERR,authn=INF+1,keys=4

- sets default level to info - enables all log levels on the http logger - disables all logging from the sql logger - sets the boot logger to debug - sets the authz logger to ERR - sets the authn logger to level 1 (slog.LevelInfo + 1) - sets the keys logger to WARN (slog.LevelWarn == 4)

func V1JSONHandler ¶

func V1JSONHandler()

V1JSONHandler configures the default json to behave like flume v1: - abbreviations for levels - durations in seconds - "errorsVerbose" key for formattable errors

func V1VerboseErrors ¶

func V1VerboseErrors(_ []string, a slog.Attr) slog.Attr

V1VerboseErrors is a ReplaceAttr function which is meant to mimic how errors were rendered in flumev1. In flumev1, an error which also implemented fmt.Formatter would result in two attributes being added to the log message: "error" and "errorVerbose". "error" would only contain the error's message, and "errorVerbose" would contain the error object formatted with fmt.Sprintf(), which typically includes the error's stacktrace or other metadata.

flumev2 has a DetailedErrors function, but that just replaces the "error" value in place with the formatted error value. We need something different to mimic flumev1/zap. See zap.NamedError() for more details.