log/slog: add `slog.DiscardHandler`

[flowchartsman]

Proposal

Add a package-level variable slog.DiscardHandler (type slog.Handler) that will discard all log output.

link to comment

Rationale

I have been happily busying myself integrating log/slog into old packages and replacing the exp import in new ones, however I've found myself implementing the same "nop handler" again and again in packages with optional logging APIs.

A common pattern in logging injection is to consume an interface or a pointer to a logging type to allow the dependency to use a derived logger with some field marking the messages as originating from that component, enabling both a standard format as well as per-component level thresholds to keep the output sane. For packages that support slog, this will likely often end up being a *slog.Logger or a slog.Handler, however I've also had to develop a series of log adapters for common dependencies which use their own concrete types, interfaces and callbacks.

In both of these cases, it is helpful to have a default fallback which logs nothing, so that the packages can be tested or used on their own without needing boilerplate guard clauses on every logging method to check for nil values. It's also helpful for less well-behaved dependencies which create their own loggers if one is not provided, some of whom are exceptionally chatty for no good reason. Packages like this are sadly far too common, and we're likely to continue seeing them, so a way to bring some sanity to the process would be very useful.

While it's true that checks for the presence of logging can be reduced by funneling all handler interaction through a single point, this introduces another sort of boilerplate for slog where Records need to be created manually, adjusting their PC to account for the extra frame as seen in the wrapping example. This is a low-level and overly-manual process just to enable conditional logging.

Currently, there doesn't seem to be a great answer for this in slog:

• there are no guards for a nil receiver on *Logger methods
• the zero value of Logger is not usable and will panic
• Loggers initialized with a nil handler will panic
• there is no way to modify a logger to change its handler or logging level once it's created, making slog.Default() unworkable as a fallback
• defaultHandler is unexported, so it cannot act as a fallback, and handlers do not provide a WithLevel or WithLeveler method, so it wouldn't work as a fallback even if it were exported.
• HandlerOptions, which allows specifying a minimum level, only applies to the built-in handlers, and there is no WithHandlerOptions that would allow derived handlers to adjust their logging level using this type.

Leaving aside the arguments on the merits of logging in packages, this pattern is nonetheless common enough that it would probably be useful to have a type DisabledHandler struct{} or even a func DisabledLogger()*Logger convenience method that could act as a default. when the zero values are nil.

[earthboundkid]

log.Logger has an optimization where it detects when the writer is io.Discard and does no allocations. Maybe slog should do the same thing.

[bcmills]

(CC @jba)

[flowchartsman]

log.Logger has an optimization where it detects when the writer is io.Discard and does no allocations. Maybe slog should do the same thing.

I'm not sure this would work in this case, since this would be an implementation at the handler level, which would mean it would only apply to the standard lib JSON and KV handlers. It would require the user to take an slog.Handler and write something like:

if config.LoggingHandler == nil {
     //default: this JSONHandler does nothing
    config.LoggingHandler = slog.NewJSONHandler(io.Discard, nil)
}

// need the handler since slog.New(nil) will panic
logger := slog.New(config.LoggingHandler)

Which still feels pretty awkward.

[jba]

I wouldn't want to make a nil *Logger meaningful. I think it would lead to hard-to-find errors where forgetting to set a logger resulted in no log output, and that is only detected when you need the log output (like during a production outage).

I think a slog.DiscardHandler variable would make sense, just as we have io.Discard. Or maybe NopHandler is a better name. Does that work for you?

[flowchartsman]

I wouldn't want to make a nil *Logger meaningful. I think it would lead to hard-to-find errors where forgetting to set a logger resulted in no log output, and that is only detected when you need the log output (like during a production outage).

Concur. Either handler name works for me and, while I like NopHandler, I think it probably serves as more of a mnemonic to call it DiscardHandler in keeping with the convention elsewhere.

This would make the fallback story for logging injection something like:

type ClientConfig struct {
    Logger: *slog.Logger
}

func NewClient(config ClientConfig) (*Client, error) {
    if config.Logger == nil {
        config.Logger = slog.New(slog.DiscardHandler)
    }
    //...
    return &Client{
        logger: config.Logger,
    }, nil
}

Which isn't too bad, and makes a DiscardLogger() *Logger redundant, unless you really care about those 9 characters ;)

[flowchartsman]

The only reason to prefer DiscardLogger() *Logger might be that it could be created fresh on invocation, which would prevent dependencies from mucking about with slog.DiscardHandler, though the flip side is that they can already call slog.SetDefault(), and it could be useful for debugging to explicitly set slog.DiscardHandler in main(). I guess it depends on your attitude towards package-level variables.

[jba]

The proposal here is to add slog.DiscardHandler as a global variable, like io.Discard, or possibly a function.

It's ready for the proposal committee.

/cc @rsc

[jsumners]

I want to cast a vote for this being added. I found myself writing the following today in a test suite because the portion of my application I was testing relies on having a logger instance, but I don't care about logs during the tests:

package main

import "log/slog"

type NullWriter struct{}

func (NullWriter) Write([]byte) (int, error) { return 0, nil }

func main() {
	logger := NullLogger()
	logger.Info("foo")
}

func NullLogger() *slog.Logger {
	return slog.New(slog.NewTextHandler(NullWriter{}, nil))
}

Reading through this thread I learned about io.Discard (I had searched for combination of "null" and "writer" but never would have guessed "Discard"). So that'll remove some code for me. But it would be really nice if we could invoke slog.NewNullLogger() or some such to avoid this sort of boilerplate.

[jba]

@flowchartsman, can you edit your top post to refer to the actual proposal (#62005 (comment))?

[jba]

@flowchartsman ... or just edit it to be the proposal.