Should a Go package ever use log.Fatal and when?

Question

I have so far avoided use of log.Fatal, but I recently co-incidentally discovered these questions; code-coverage and tests-using-log-fatal.

One of the comments from the 100 code coverage questions says:

... In the vast majority of cases log.Fatal should be only be used in main, or init functions (or possibly some things meant to be called only directly from them)"

It go me thinking, so I began to look at the standard library code provided with Go. There are lots of examples where the test code in the library makes use of log.Fatal which seems fine. There are a few examples outside of the test code, such as in net/http, shown below:

// net/http/transport.go 
func (t *Transport) putIdleConn(pconn *persistConn) bool {
    ...
    for _, exist := range t.idleConn[key] {
        if exist == pconn {
            log.Fatalf("dup idle pconn %p in freelist", pconn)
        }
    }
    ...
}

If its is best practice to avoid use of log.Fatal, why is it used at all in the standard libraries, I would have expected just return an error. It seems unfair to the user of the library to cause os.Exit to be called and not providing any chance for the application to clean-up.

I may be naive, so hence my question as a better practice would seem to be to call log.Panic which can be recovered and my theoretical long running stable application might have a chance of rising from the ashes.

So what would best-practise say for Go about when should log.Fatal should be used?

Answer 1

It might be just me, but here is how I use log.Fatal. As per UNIX conventions, a process which encounters an error should fail as early as possible with a non-zero exit code. This lead me to the following guidelines to use log.Fatal when…

1. …an error happens in any of my func init(), as these happen when the imports are processed or before the main func is called, respectively. Conversely, I only do stuff not directly affecting the unit of work the library or cmd is supposed to do. For example, I set up logging and check wether we have a sane environment and parameters. No need to run main if we have invalid flags, right? And if we can not give proper feedback, we should tell this early.
2. …an error happens of which I know is irrecoverable. Let's assume we have a program which creates a thumbnail of an image file given on the command line. If this file does not exist or is unreadable because of insufficient permissions, there is no reason to continue and this error can not be recovered from. So we adhere to the conventions and fail.
3. …an error occurs during a process which might not be reversible. This is kind of a soft definition, I know. Let me illustrate that. Let's assume we have an implementation of cp, and it was started to be non-interactive and recursively copy a directory. Now, let's assume we encounter a file in the target directory which has the same name (but different content) as a file to be copied there. Since we can not ask the user to decide what to do and we can not copy this file, we have a problem. Because the user will assume that the source and the target directories are exact copies when we finish with exit code zero, we can not simply skip the file in question. However, we can not simply overwrite it, since this might potentially destroy information. This is a situation we can not recover from per explicit request by the user, and so I'd use log.Fatal to explain the situation, hereby obeying the principle to fail as early as possible.