Capstone 3: middleware and logging
Three wrappers cover the concerns every request shares: an id, a log line and a recovered panic. They are the middleware of lesson 95 with a real logger and a real store behind them, and they are applied once in Routes, so a test and the server run the same chain.
The chain
recoverer is the outermost, so a panic in the id wrapper or the logger is caught too. requestID runs next, and logging is inside it so the log can read the id from the context. The mux is the last and knows nothing of the three.
func (a *API) Routes() http.Handler {
mux := http.NewServeMux()
mux.HandleFunc("GET /healthz", a.health)
mux.HandleFunc("GET /api/notes", a.list)
mux.HandleFunc("POST /api/notes", a.create)
mux.HandleFunc("GET /api/notes/{id}", a.get)
mux.HandleFunc("PUT /api/notes/{id}", a.update)
mux.HandleFunc("DELETE /api/notes/{id}", a.delete)
return a.recoverer(a.requestID(a.logging(mux)))
}
The order is the whole design. A header that the logger needs must be set before it runs, and a panic that the recoverer catches must unwind through the logger. Swapping two wrappers changes what a log line contains, which is why the chain is written in one place and reviewed as a line.
The request id
The id is a counter with a prefix, which is enough for one process, and it is put in the context and in a response header. A service behind a proxy that already sends an id reads it instead, and a service that must correlate across processes uses a UUID or a trace id. The context key is a private type, the rule from lesson 73.
package api
import (
"context"
"fmt"
"net/http"
"sync/atomic"
"time"
)
type contextKey string
const requestIDKey contextKey = "request_id"
var requestCounter atomic.Int64
// requestID gives every request an id and puts it in the context.
func (a *API) requestID(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
id := fmt.Sprintf("req-%d", requestCounter.Add(1))
ctx := context.WithValue(r.Context(), requestIDKey, id)
w.Header().Set("X-Request-ID", id)
next.ServeHTTP(w, r.WithContext(ctx))
})
}
type statusWriter struct {
http.ResponseWriter
status int
}
func (s *statusWriter) WriteHeader(code int) {
s.status = code
s.ResponseWriter.WriteHeader(code)
}
A counter resets when the process restarts, so two ids can name two different requests in two log files. That is acceptable for a single service and not for a fleet; the page says so rather than pretending the id is globally unique.
The log line
The logger wraps the writer in a small statusWriter that records the status, then writes one line with the id, the method, the path, the status and the duration. The default status is 200 because a handler that only writes a body never calls WriteHeader.
func (a *API) logging(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
start := time.Now()
sw := &statusWriter{ResponseWriter: w, status: http.StatusOK}
next.ServeHTTP(sw, r)
id, _ := r.Context().Value(requestIDKey).(string)
a.log.Info("request",
"id", id,
"method", r.Method,
"path", r.URL.Path,
"status", sw.status,
"duration", time.Since(start).Round(time.Millisecond).String(),
)
})
}
// recoverer turns a panic in a handler into a 500 and a log line.
One line per request is the right granularity for a service: enough to count, filter and trace, little enough to keep. The duration is a string from time.Since rounded to the millisecond, which a log system can parse or ignore. The handler does not log, so the format is the same for every route.
The recoverer
A panic in a handler ends the whole process without this wrapper. The deferred recover logs the value and answers a 500 with the error shape; the stack is not sent to the client. The wrapper is outside the logger, so the log line of the failed request is still written before the recover runs, with the status the writer recorded.
func (a *API) recoverer(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
if v := recover(); v != nil {
a.log.Error("panic", "value", v)
writeError(w, http.StatusInternalServerError, "internal error")
}
}()
next.ServeHTTP(w, r)
})
}
The order has a subtlety: a panic happens inside the mux, the logger's next.ServeHTTP does not return normally, so its line is not written and the deferred recover in the outer wrapper does the logging. A service that wants both lines moves the recover inside the logger and accepts that a panic in the logger itself is not caught.
A run
The demo configures a text logger with the timestamp and the duration removed so the output is stable, and makes two requests. Each response carries its request id, and each log line names it.
package main
import (
"fmt"
"log/slog"
"net/http"
"net/http/httptest"
"os"
"example.com/notesapi/internal/api"
"example.com/notesapi/internal/store"
)
func main() {
opts := &slog.HandlerOptions{
ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
if a.Key == slog.TimeKey && len(groups) == 0 {
return slog.Attr{}
}
if a.Key == "duration" {
return slog.Attr{}
}
return a
},
}
logger := slog.New(slog.NewTextHandler(os.Stdout, opts))
a := api.New(store.NewMemory(), logger)
srv := httptest.NewServer(a.Routes())
defer srv.Close()
for _, path := range []string{"/api/notes", "/healthz"} {
resp, err := http.Get(srv.URL + path)
if err != nil {
panic(err)
}
resp.Body.Close()
fmt.Println("request id:", resp.Header.Get("X-Request-ID"), "status:", resp.StatusCode)
}
}
go run ./cmd/l132
level=INFO msg=request id=req-1 method=GET path=/api/notes status=200
request id: req-1 status: 200
level=INFO msg=request id=req-2 method=GET path=/healthz status=200
request id: req-2 status: 200
The id in the header and the id in the line are the same, which is the correlation the wrapper exists for. A user who reports a problem quotes the header value, and the operator finds the line. The two requests were logged in the order they finished, which for one client is the order they were made.
One place per concern
The id, the log and the recovery are three wrappers and not three snippets in every handler. The test of a handler does not configure a logger, because the handler does not have one; the service test of lesson 133 turns the middleware on and checks the header. The next lesson writes those tests.
Exercises
- Read an incoming X-Request-ID header when it is present and generate one otherwise. Which wrapper changes, and what does a proxy in front need to do?
- Add a route that panics and request it through the demo. Which line is logged, and what status does the client see?
- Move the recoverer inside the logger and panic again. Which lines are logged now, and which wrapper is no longer protected?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Which wrapper is outermost?
Answer
The recoverer
It must catch every inner panic.
-
Where does the id live?
Answer
In the request context and a response header
A private context key carries it.
-
Why is the counter not a global id?
Answer
It resets with the process
A fleet needs a UUID or a trace.
-
What records the status?
Answer
A ResponseWriter wrapper
WriteHeader is intercepted.
-
What status does a body-only handler record?
Answer
200
The default of the wrapper.
-
How many log lines per request?
Answer
One
The middleware writes it.
-
What does the recoverer send the client?
Answer
A 500 with the error shape
The stack belongs in the log.
-
What is the subtlety of the order with a panic?
Answer
The logger line is skipped because next does not return
The outer defer logs the failure.
-
Why does the handler not log?
Answer
The middleware does, so the format is the same for every route
One place per concern.
-
What does the test of a handler need?
Answer
A store and a recorder, not a logger
The handler has no logger.
The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev