logging

name	logging
description	Guide logging practices based on Dave Cheney's minimalist philosophy. Use when adding log.Info/Debug/Error/Warn/Fatal calls, reviewing logging code, handling errors with log+return pattern, discussing log levels, or designing error handling strategies.

Apply Dave Cheney's logging philosophy: simplify ruthlessly, handle errors properly, and log only what matters. Only two log levels matter: Info (for operators/users) and Debug (for developers) Never log an error AND return it (causes duplicate logs up the stack) Never log errors in library code (caller decides what to do) Let errors bubble up to where they can be meaningfully handled Warning level: Remove it. "Nobody reads warnings" - either it's an error or info Fatal level: Avoid it. Bypasses `defer`, prevents cleanup. Let errors bubble to `main()` Error level: Rethink it. If handled, it's info. If not handled, return it to caller Exception: Warnings from runtimes and external libraries should be logged at warning level (you don't control these sources) Prefer structured logging formats over string interpolation Let errors propagate to where they can be meaningfully handled ```go // GOOD: Just return (let caller decide) if err != nil { return fmt.Errorf("connect: %w", err) } ``` At the boundary where errors become user-facing unexpected failures (e.g., 5xx responses), error-level logging is correct - The error chain ends here - no caller to return to - The user receives a generic message (for security/UX) - Operators need the full error details for debugging ```go // At HTTP handler boundary - error level is appropriate if err != nil { log.Error("unexpected failure", "error", err, "request_id", requestID, ) http.Error(w, "Internal Server Error", http.StatusInternalServerError) return } ``` This is NOT the same as logging mid-stack - this is the terminal handler where errors are finally consumed, not propagated. When logging is appropriate, prefer structured formats ```go // Prefer structured fields over string interpolation log.Info("request completed", "method", r.Method, "path", r.URL.Path, "duration", time.Since(start), ) ```

<anti_patterns> Logging an error AND returning it causes duplicate logs up the stack

// BAD: Log and return (duplicate logs)
if err != nil {
    log.Error("failed to connect", err)
    return err
}

</example>
<instead>Just return the error and let the caller decide</instead>

Warning that nobody will act on ```go // BAD: Warning that nobody will act on log.Warn("connection pool running low") ``` Either info (if expected) or error (if action needed): `log.Info("connection pool at 80% capacity")`

<best_practices> Is this log statement for users (info) or developers (debug)? Am I logging an error AND returning it? (Remove the log) Is this a terminal handler (5xx boundary)? (Error level is appropriate here) Is this a warning? (Convert to info or error, or remove) Is this Fatal/panic in library code? (Return error instead) Does this log message help the operator understand system state? </best_practices>

Based on: Let's talk about logging by Dave Cheney (2015)