Error mapping and structured logging

One place turns domain errors into HTTP statuses, and your logs become searchable.

Topic 82 of 98 · 5 min to read · 50 min to build

After this topic you can

Build one error boundary that maps domain errors to HTTP statuses.
Write structured logs with log/slog that include a request ID.
Explain the difference between liveness and readiness health checks.

Two jobs that are easy to confuse

When something goes wrong, two different audiences need two different things. The client needs a status code and a short, safe message. You need the full detail, so you can find out what happened.

Mixing them up hurts both ways. Returning the internal error to the client leaks your table names, your file paths, and sometimes your data. Logging nothing means you cannot debug it at all.

Structured logging is the second half. A log line written as a sentence is hard to filter. A log line written as key-and-value pairs can be filtered by status=500, counted and alerted on.

One error boundary for the whole API

internal/httpx/errors.go

1func FromError(w http.ResponseWriter, r *http.Request, err error) {
2	var ve *ValidationError
3
4	switch {
5	case errors.Is(err, context.Canceled):
6		return                                       // client went away; nothing to send
7
8	case errors.Is(err, ErrNotFound):
9		Error(w, 404, "not found")
10
11	case errors.Is(err, ErrForbidden):
12		Error(w, 404, "not found")                   // hide existence
13
14	case errors.Is(err, ErrEmailTaken):
15		Error(w, 409, "email already registered")
16
17	case errors.Is(err, ErrInvalidCredentials):
18		Error(w, 401, "invalid credentials")
19
20	case errors.Is(err, ErrValidation):
21		Error(w, 422, err.Error())
22
23	case errors.As(err, &ve):
24		JSON(w, 422, map[string]string{ve.Field: ve.Msg})
25
26	default:
27		// the detail goes to the log, with the request id
28		slog.ErrorContext(r.Context(), "unhandled error", "err", err)
29		Error(w, 500, "internal server error")       // the client learns nothing
30	}
31}

Watch out: Never return an internal error message to a client. A raw SQL error leaks your table names and column names, and a stack trace leaks your source paths. Log the detail with a request id, return a generic message and a status.

Structured logging with log/slog

log/slog has been in the standard library since Go 1.21. For most services it removes the need for a logging dependency.

internal/logging/logging.go

1func Setup(env string) {
2	var h slog.Handler
3	if env == "production" {
4		h = slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo})
5	} else {
6		h = slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelDebug})
7	}
8	slog.SetDefault(slog.New(h))
9}
10
11slog.Info("request completed",
12	"method", r.Method,
13	"path", r.URL.Path,
14	"status", status,
15	"duration_ms", ms,
16	"request_id", rid,
17)

JSON in production because machines read it; text in development because you do.

Request IDs tie a failure together

internal/middleware/requestid.go

1func RequestID(next http.Handler) http.Handler {
2	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
3		id := r.Header.Get("X-Request-ID")
4		if id == "" {
5			var b [8]byte
6			rand.Read(b[:])
7			id = hex.EncodeToString(b[:])
8		}
9		w.Header().Set("X-Request-ID", id)
10
11		// a logger carrying the id, put into the context
12		ctx := context.WithValue(r.Context(), loggerKey{}, slog.Default().With("request_id", id))
13		next.ServeHTTP(w, r.WithContext(ctx))
14	})
15}

Now every line from one request shares an id, and the client got it in the response header. "It failed at 2pm" becomes one grep.

Logging rules

Never log passwords, tokens, whole Authorization headers, card numbers, or full request bodies. Anyone who can read the logs can then read those too.
Handle an error once. Log it or return it, not both, or one failure appears five times at five layers.
Log at the boundary, where you decide the HTTP status. That is where you have the request id and the wrapped error chain.
Levels mean something. Error means a human should look. If everything is Error, nothing is.
A cancelled request is not a 500. context.Canceled means the client left. Do not page anyone for it.

Health checks: two, not one

health.go

1mux.HandleFunc("GET /livez", func(w http.ResponseWriter, r *http.Request) {
2	w.WriteHeader(200)                     // is the process wedged? restart me if so
3})
4
5mux.HandleFunc("GET /readyz", func(w http.ResponseWriter, r *http.Request) {
6	ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
7	defer cancel()
8	if err := db.PingContext(ctx); err != nil {
9		httpx.Error(w, 503, "database unavailable")   // stop sending me traffic
10		return
11	}
12	httpx.JSON(w, 200, map[string]string{"status": "ok"})
13})

Keep them separate. Wiring a DB ping into liveness means a brief database blip restarts every instance at once.

The short version

One function maps domain errors to statuses. Handlers never choose a status themselves.
Internal detail goes to the log with a request id; the client gets a generic message.
log/slog with key–value pairs. JSON in production, text in development.
Liveness and readiness are different checks. Do not merge them.

Remember: The client gets a status and a safe message. You get the detail, the request id, and enough to find it in the logs.

Build this before moving on

Add the error boundary, slog setup, request-id middleware, and both health endpoints. Force a database error and confirm the client sees a generic 500 while the log has the full detail and the id.

Then try these in your own editor

1Force a database error and confirm the client sees a generic 500 while the log has the detail and a request id.
2Add the request id to the response header, then find that one request in your logs by grepping the id.
3Kill a request mid-flight with Ctrl-C in curl and confirm it does not log as a 500.
4Switch the handler from Text to JSON and diff how readable each is for a human and for jq.

Official documentation

Check yourselfTake the Production test