Getting a Client

go get github.com/anthropics/anthropic-sdk-go

import (
    "github.com/anthropics/anthropic-sdk-go"
    "github.com/anthropics/anthropic-sdk-go/option"
)

// Reads ANTHROPIC_API_KEY from the environment.
client := anthropic.NewClient()

// Or pass it explicitly, if you load config yourself.
client := anthropic.NewClient(option.WithAPIKey(key))

Build the client once, at startup, and pass it around. It is safe for concurrent use and holds a connection pool — constructing one per request throws away keep-alive and gives you a fresh TLS handshake every time.

The First Call

resp, err := client.Messages.New(ctx, anthropic.MessageNewParams{
    Model:     "claude-opus-5",
    MaxTokens: 16000,
    Messages: []anthropic.MessageParam{
        anthropic.NewUserMessage(anthropic.NewTextBlock("Summarise this changelog in three bullets.")),
    },
})
if err != nil {
    return fmt.Errorf("summarise changelog: %w", err)
}

Two things about that snippet are worth slowing down on.

The model is a plain string. The SDK ships typed constants (anthropic.ModelClaudeOpus4_8 and friends), but anthropic.Model is an alias for string, so a model that has no constant yet is passed as its id. Either form compiles; check the SDK release notes before assuming a constant exists for the model you want.

MaxTokens is a ceiling, not a target. It is the point at which generation is cut off mid-sentence, and the model is not told about it. Setting it to 500 because you want a short answer does not produce a short answer — it produces a truncated one. Ask for brevity in the prompt and leave the ceiling generous. For non-streaming requests, something around 16000 keeps you clear of both truncation and the SDK’s HTTP timeout.

Content Is a List of Blocks, Not a String

This is where the first hour usually goes. A response is not resp.Text. It is resp.Content, a slice of union values that can hold text, thinking, tool calls and more:

for _, block := range resp.Content {
    switch variant := block.AsAny().(type) {
    case anthropic.TextBlock:
        fmt.Println(variant.Text)
    case anthropic.ThinkingBlock:
        // Reasoning, when you have asked for it to be shown.
        log.Debug("model reasoning", "text", variant.Thinking)
    }
}

block.AsAny() is the accessor that gets you a concrete type to switch on. Reaching for resp.Content[0].Text and hoping works right up until the day a thinking block or a tool call lands in position zero, at which point you silently return an empty string. Write the type switch once, in a helper, and use it everywhere:

// firstText returns the first text block in a response, or "" if there is none.
func firstText(msg *anthropic.Message) string {
    for _, block := range msg.Content {
        if t, ok := block.AsAny().(anthropic.TextBlock); ok {
            return t.Text
        }
    }
    return ""
}

Thinking, and Why You Probably Want It On

Current Claude models can reason before answering. The recommended mode is adaptive — you do not budget tokens for it, the model decides how much thinking a given request deserves:

adaptive := anthropic.ThinkingConfigAdaptiveParam{}

params := anthropic.MessageNewParams{
    Model:     "claude-opus-5",
    MaxTokens: 16000,
    Thinking:  anthropic.ThinkingConfigParamUnion{OfAdaptive: &adaptive},
    Messages:  messages,
}

There is no ThinkingConfigParamOfAdaptive helper — you construct the union literal and take the address of the variant, as above. That trips people up because almost every other option in the SDK does have a constructor function.

A word of warning if you are carrying settings over from older code: the fixed thinking budget (ThinkingConfigParamOfEnabled(N)) is gone on current models and returns a 400 rather than being ignored. If you want to spend less, the lever is effort, not a token budget — and effort lives inside output_config, not at the top level of the request.

The counter-intuitive part: on the newest models, turning thinking off is not reliably a cost saving. Lower effort with thinking on generally beats thinking off, and disabling it has failure modes of its own. Leave it on and turn effort down.

Streaming

Anything a user waits for should stream. It is not just perceived speed — a long non-streaming request is also the easiest way to hit an HTTP timeout.

stream := client.Messages.NewStreaming(ctx, anthropic.MessageNewParams{
    Model:     "claude-opus-5",
    MaxTokens: 64000,
    Messages:  messages,
})

for stream.Next() {
    event := stream.Current()
    switch ev := event.AsAny().(type) {
    case anthropic.ContentBlockDeltaEvent:
        switch delta := ev.Delta.AsAny().(type) {
        case anthropic.TextDelta:
            fmt.Print(delta.Text)
        }
    }
}
if err := stream.Err(); err != nil {
    return fmt.Errorf("stream response: %w", err)
}

Two nested type switches is not the prettiest Go you will write, but the shape is stable: outer switch on the event, inner switch on the delta.

Always check stream.Err(). stream.Next() returning false means “no more events” — it does not tell you whether that was a clean finish or a dropped connection. A loop that ignores Err() will happily serve a truncated answer as if it were complete.

If you want the whole message and the incremental deltas, accumulate as you go. There is no GetFinalMessage() on the Go stream:

stream := client.Messages.NewStreaming(ctx, params)

var message anthropic.Message
for stream.Next() {
    message.Accumulate(stream.Current())
    // ... also forward the delta to the user here
}
if err := stream.Err(); err != nil {
    return err
}
// message.Content is now the complete response.

Raising MaxTokens to 64000 in the streaming example is deliberate. Timeouts stop being the binding constraint once you stream, so you can give the model room.

Streaming to a Browser

Server-sent events are the path of least resistance, and Go’s http.ResponseController makes the flushing straightforward:

func (h *Handler) stream(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "text/event-stream")
    w.Header().Set("Cache-Control", "no-cache")
    w.Header().Set("X-Accel-Buffering", "no") // stop nginx buffering the stream

    rc := http.NewResponseController(w)

    stream := h.client.Messages.NewStreaming(r.Context(), params)
    for stream.Next() {
        ev, ok := stream.Current().AsAny().(anthropic.ContentBlockDeltaEvent)
        if !ok {
            continue
        }
        delta, ok := ev.Delta.AsAny().(anthropic.TextDelta)
        if !ok {
            continue
        }

        // SSE data frames must not contain raw newlines.
        payload, _ := json.Marshal(delta.Text)
        if _, err := fmt.Fprintf(w, "data: %s\n\n", payload); err != nil {
            return // client hung up
        }
        if err := rc.Flush(); err != nil {
            return
        }
    }

    if err := stream.Err(); err != nil {
        slog.Error("llm stream failed", "err", err)
        fmt.Fprint(w, "event: error\ndata: {}\n\n")
        _ = rc.Flush()
        return
    }
    fmt.Fprint(w, "event: done\ndata: {}\n\n")
    _ = rc.Flush()
}

Three details that cost me an afternoon each:

• X-Accel-Buffering: no. Without it nginx buffers your stream and delivers the whole thing at the end, which looks exactly like streaming being broken. (Nginx has strong opinions about proxied responses generally — I ran into a related set of them in making Nginx cache cookie aware.)
• JSON-encode the delta. A model can and will emit a newline mid-sentence, and a bare newline terminates an SSE frame.
• Pass r.Context(), not context.Background(). When the user closes the tab, the request context cancels, the SDK aborts the HTTP call, and you stop paying for tokens nobody will read.

Deadlines and Cancellation

Context is not decoration here. It is the only thing standing between a slow model call and a goroutine that lives forever:

ctx, cancel := context.WithTimeout(r.Context(), 90*time.Second)
defer cancel()

resp, err := client.Messages.New(ctx, params)

Set the deadline against how long the work should take, not a habit. A classification call has no business taking 90 seconds; a long agentic turn on a hard problem might legitimately run for several minutes. If you have not internalised how deadlines propagate through a call chain, understanding Golang context covers the machinery.

The corollary at shutdown: an in-flight model call is exactly the kind of long request that a naive SIGTERM handler will sever. Drain it properly — see graceful shutdown in Go web services.

Errors Worth Distinguishing

The SDK returns typed errors. Use errors.As to get at the status code rather than matching on message strings:

resp, err := client.Messages.New(ctx, params)
if err != nil {
    var apiErr *anthropic.Error
    if errors.As(err, &apiErr) {
        switch apiErr.StatusCode {
        case http.StatusTooManyRequests:
            return fmt.Errorf("rate limited: %w", ErrRetryable)
        case http.StatusBadRequest:
            // Your request is malformed. Retrying will not help.
            return fmt.Errorf("bad request to model: %w", err)
        default:
            return fmt.Errorf("model call failed (%d): %w", apiErr.StatusCode, err)
        }
    }
    // Not an API error: context cancellation, DNS, TLS, connection reset.
    return fmt.Errorf("model call failed: %w", err)
}

Wrapping with %w at each layer is what lets the HTTP boundary decide the status code without every layer needing to know about HTTP — the same pattern I laid out in error handling in Go.

The SDK already retries for you. By default it retries a couple of times on 408, 409, 429, 5xx and connection errors, with backoff. Two consequences people miss:

1. Do not add your own retry loop on top without lowering the SDK’s. Three of yours around two of its is nine attempts and a long tail of latency.
2. Wall-clock can reach timeout × (attempts + 1). Your context deadline is the real budget — set it deliberately, because the retry behaviour will happily use all of it.

A Refusal Is Not an Error

This one surprises people. If a safety classifier declines a request, you get HTTP 200 — a perfectly successful response whose StopReason says the model declined:

if resp.StopReason == anthropic.StopReasonRefusal {
    slog.Warn("model declined",
        "category", resp.StopDetails.Category,
        "explanation", resp.StopDetails.Explanation)
    return "", ErrDeclined
}

err is nil. resp.Content may hold nothing useful. Code that goes straight from if err != nil to reading Content[0] treats this as an empty answer and moves on. Check StopReason before you read content — and note the other values you care about: max_tokens means you were truncated, and tool_use means the model is waiting on you (which is a whole article of its own).

Watch the Usage Numbers

Every response carries a token accounting:

slog.Info("model call",
    "input_tokens", resp.Usage.InputTokens,
    "output_tokens", resp.Usage.OutputTokens,
    "cache_read", resp.Usage.CacheReadInputTokens,
    "cache_write", resp.Usage.CacheCreationInputTokens,
)

Log these from day one. They are the only ground truth about what a feature costs, and CacheReadInputTokens in particular is how you find out that your prompt caching silently stopped working three deploys ago — the failure mode there is not an error, just a bigger invoice. That is its own post, because it is the single biggest lever on what an LLM feature costs to run.

A structured logger pays for itself here: these are five numeric fields per call that you will want to aggregate later, which is exactly the case for structured logging with log/slog.

Checklist

• One client, built at startup, shared across handlers.
• Iterate resp.Content with a type switch; never index blindly into it.
• Adaptive thinking on; tune cost with effort, not by disabling it.
• Stream anything a human waits for, and always check stream.Err().
• r.Context() all the way down, with a deliberate deadline.
• errors.As into *anthropic.Error for status-code branching.
• Do not stack your retries on the SDK’s.
• Check StopReason before reading content — a refusal returns 200.
• Log the usage fields from the first commit.

Conclusion

The API surface is small — one endpoint, one loop, a handful of block types. What makes an LLM call different from any other HTTP call in your service is that it is slow, occasionally non-deterministic, priced per token, and able to succeed while declining to do what you asked. Go gives you good tools for exactly those problems, provided you use the context properly and read the response as the structured thing it is rather than the string you wish it were.

The Problem With the Obvious Version

// Do not ship this.
func fetchAll(urls []string) {
    var wg sync.WaitGroup
    for _, url := range urls {
        wg.Add(1)
        go func() {
            defer wg.Done()
            fetch(url)
        }()
    }
    wg.Wait()
}

Three separate problems:

1. No limit. len(urls) concurrent requests. The remote service rate-limits you, or your file descriptors run out, or both.
2. No errors. fetch returns one and it goes nowhere.
3. No cancellation. If the caller gives up, every goroutine keeps running to completion.

The concurrency itself is not the mistake — the missing back pressure is.

The Classic Channel Pool

The traditional shape is a jobs channel, a fixed number of workers reading from it, and a results channel:

type job struct {
    ID  int
    URL string
}

type result struct {
    JobID int
    Body  []byte
    Err   error
}

func workerPool(ctx context.Context, jobs []job, workers int) []result {
    jobCh := make(chan job)
    resCh := make(chan result, len(jobs))

    var wg sync.WaitGroup
    for i := 0; i < workers; i++ {
        wg.Add(1)
        go func(workerID int) {
            defer wg.Done()
            for j := range jobCh {
                body, err := fetch(ctx, j.URL)
                select {
                case resCh <- result{JobID: j.ID, Body: body, Err: err}:
                case <-ctx.Done():
                    return
                }
            }
        }(i)
    }

    // Feed the workers, stopping early if the caller cancels.
    go func() {
        defer close(jobCh)
        for _, j := range jobs {
            select {
            case jobCh <- j:
            case <-ctx.Done():
                return
            }
        }
    }()

    wg.Wait()
    close(resCh)

    out := make([]result, 0, len(jobs))
    for r := range resCh {
        out = append(out, r)
    }
    return out
}

This is worth understanding because you will read it in a lot of codebases, and because it shows the mechanics plainly. Note two things that are easy to get wrong:

• close(jobCh) is the workers’ exit signal. for j := range jobCh ends when the channel closes. Forget the close and wg.Wait() blocks forever.
• Every channel send is paired with <-ctx.Done(). Without that, a worker sending to a full resCh that nobody is reading leaks for the lifetime of the process.

It is also about forty lines to do something the standard extended library does in eight.

The errgroup Version

golang.org/x/sync/errgroup is a sync.WaitGroup that also collects the first error and cancels its siblings. SetLimit turns it into a bounded pool:

import "golang.org/x/sync/errgroup"

func fetchAll(ctx context.Context, urls []string) ([][]byte, error) {
    bodies := make([][]byte, len(urls))

    g, ctx := errgroup.WithContext(ctx)
    g.SetLimit(10) // at most 10 in flight

    for i, url := range urls {
        g.Go(func() error {
            body, err := fetch(ctx, url)
            if err != nil {
                return fmt.Errorf("fetch %s: %w", url, err)
            }
            // Each goroutine owns exactly one slot: no mutex needed.
            bodies[i] = body
            return nil
        })
    }

    if err := g.Wait(); err != nil {
        return nil, err
    }
    return bodies, nil
}

That is the whole pool. Behaviour worth knowing:

• g.Go blocks once the limit is reached, until a slot frees up. The for loop becomes its own back pressure — no jobs channel needed.
• errgroup.WithContext returns a derived context that is cancelled the moment any goroutine returns a non-nil error. Shadowing ctx with it, as above, is deliberate: every fetch gets the cancellable one.
• g.Wait() returns the first error, and waits for the rest regardless. Later errors are discarded — if you need all of them, collect them yourself (errors.Join is a good fit, see error handling in Go).
• Writing to bodies[i] is safe without a mutex because each goroutine writes one distinct element. Different elements of a slice are different memory; that is not a data race. Appending to a shared slice, or writing to a shared map, absolutely is — see concurrent map writing and reading in Go for what that failure looks like.

A Note on Loop Variables

The example above relies on Go 1.22’s per-iteration loop variables. Before 1.22, i and url were shared across iterations and every goroutine would see the final values — the single most common concurrency bug in Go. On older versions you must copy them:

for i, url := range urls {
    i, url := i, url // required before Go 1.22
    g.Go(func() error { /* ... */ })
}

Since Go 1.22 the copy is unnecessary. Leaving it in is harmless, and I still write it in code that must build on older toolchains. The loop semantics change was one of the more consequential recent additions to the language — I touched on the surrounding rules in mastering Golang for loops.

Streaming Results Instead of Preallocating

Indexing into a preallocated slice only works when you know the number of jobs up front. For a stream, send results down a channel and read them concurrently:

func processStream(ctx context.Context, in <-chan job, workers int) (<-chan result, func() error) {
    out := make(chan result)

    g, ctx := errgroup.WithContext(ctx)
    g.SetLimit(workers)

    go func() {
        // Closing `out` after every worker has finished lets the consumer
        // range over it and stop naturally.
        defer close(out)

        for j := range in {
            g.Go(func() error {
                body, err := fetch(ctx, j.URL)
                if err != nil {
                    return fmt.Errorf("job %d: %w", j.ID, err)
                }
                select {
                case out <- result{JobID: j.ID, Body: body}:
                    return nil
                case <-ctx.Done():
                    return ctx.Err()
                }
            })
        }
        _ = g.Wait()
    }()

    return out, g.Wait
}

The consumer ranges over out and then calls the returned function to get the error:

results, wait := processStream(ctx, jobs, 8)
for r := range results {
    save(r)
}
if err := wait(); err != nil {
    return fmt.Errorf("process stream: %w", err)
}

g.Wait() is safe to call more than once — subsequent calls return the same error immediately.

Picking the Limit

There is no universal number, but there is a reliable way to think about it.

CPU-bound work — parsing, hashing, image resizing, compression — saturates at roughly the number of cores. More goroutines just add scheduling overhead:

g.SetLimit(runtime.GOMAXPROCS(0))

I/O-bound work — HTTP calls, database queries, object storage — spends most of its time waiting, so the useful limit is much higher. But it is not “as high as possible”: it is whatever the slowest downstream dependency can absorb. If your database pool has 25 connections, a pool of 200 workers means 175 goroutines queueing on a mutex inside database/sql while your latency graph climbs.

// Match the constraint that actually binds.
g.SetLimit(db.Stats().MaxOpenConnections)

For outbound HTTP, remember that Go’s default transport keeps only 2 idle connections per host. Exceed that and you are opening a fresh TCP connection — plus a TLS handshake — for each extra request:

transport := http.DefaultTransport.(*http.Transport).Clone()
transport.MaxIdleConnsPerHost = 50
transport.MaxConnsPerHost = 50
client := &http.Client{Transport: transport, Timeout: 10 * time.Second}

Then set the pool limit to match. Tuning one without the other gets you nothing.

Whatever you pick, measure it. Run the job at 5, 10, 25 and 50 and look at total wall time and downstream latency — the fastest setting for your batch is often the one that makes everything else on the system slower. Load testing is the honest way to find out; I wrote about a lightweight setup in an easy way to load test your web apps.

Not Every Goroutine Belongs in a Pool

A pool is for a batch of similar work. Some situations want something else:

Waiting on several different things at once — no limit needed, just a group:

g, ctx := errgroup.WithContext(ctx)

var user *User
var orders []Order

g.Go(func() (err error) { user, err = loadUser(ctx, id); return })
g.Go(func() (err error) { orders, err = loadOrders(ctx, id); return })

if err := g.Wait(); err != nil {
    return nil, fmt.Errorf("load profile: %w", err)
}

Three sequential 100ms calls become one 100ms call. This is the highest-value use of errgroup in a typical request handler, and it needs no pool at all.

Work that must happen in order — a pool is the wrong shape entirely; you want a single consumer, like the simple queue implementation I wrote about earlier.

Fire-and-forget background work — resist it. A goroutine started in a request handler outlives the request, holds whatever it captured, and will be killed mid-flight when the process shuts down. If it matters, it belongs in a durable queue; if it does not, do it inline. The same reasoning applies at shutdown time, which I covered in graceful shutdown in Go web services.

Only trying if there is capacity — TryGo starts the goroutine only if a slot is free, and reports whether it did:

if !g.TryGo(func() error { return prefetch(ctx, url) }) {
    // Pool is busy; skip this optional work rather than blocking.
    metrics.PrefetchSkipped.Inc()
}

Pitfalls

Panic recovery is worth spelling out, because one bad input taking down the whole process is a common way for batch jobs to fail:

g.Go(func() (err error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("panic processing %s: %v", url, r)
        }
    }()
    return process(ctx, url)
})

The named return value err is what makes this work — the deferred function assigns to it after the panic is recovered.

Conclusion

The pattern is small: pick a limit that matches your real bottleneck, use errgroup.WithContext so failures cancel their siblings, return errors instead of logging them, and give every blocking operation a context. Most of the time that is eight lines and no channel plumbing at all. Save the hand-rolled channel pool for the cases where you genuinely need to stream results or vary the shape of the work — and when you do write one, remember to close the jobs channel.

One place this pattern turns up more than you would expect: running the tool calls an LLM asks for, several at a time but not unboundedly — see tool use in Go. And when a pool does leak a worker, Go 1.27’s goroutine leak profile will now name it — what’s new in Go 1.27.

What Actually Happens on Shutdown

When your orchestrator wants a container gone, it sends SIGTERM and starts a countdown. If the process is still alive when the countdown ends, it gets SIGKILL, which cannot be caught.

A Go program with no signal handling takes the default action for SIGTERM: immediate termination. Every open connection is severed. Any request that was 90% done is simply gone — the client sees a reset, your retry budget takes the hit, and if that request was a payment you now have a support ticket.

Graceful shutdown means using the window between SIGTERM and SIGKILL to:

1. Stop accepting new connections.
2. Let in-flight requests finish.
3. Drain background workers.
4. Close databases, caches and queues.
5. Exit before the countdown runs out.

The Twenty Lines

package main

import (
    "context"
    "errors"
    "log/slog"
    "net/http"
    "os"
    "os/signal"
    "syscall"
    "time"
)

func main() {
    srv := &http.Server{
        Addr:              ":8080",
        Handler:           newRouter(),
        ReadHeaderTimeout: 5 * time.Second,
        ReadTimeout:       15 * time.Second,
        WriteTimeout:      30 * time.Second,
        IdleTimeout:       60 * time.Second,
    }

    // ctx is cancelled the first time we receive SIGINT or SIGTERM.
    ctx, stop := signal.NotifyContext(context.Background(),
        os.Interrupt, syscall.SIGTERM)
    defer stop()

    go func() {
        slog.Info("listening", "addr", srv.Addr)
        // ListenAndServe always returns a non-nil error; ErrServerClosed
        // is the expected one after Shutdown.
        if err := srv.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
            slog.Error("listen failed", "err", err)
            os.Exit(1)
        }
    }()

    <-ctx.Done()
    stop() // restore default handling: a second Ctrl-C now kills us
    slog.Info("shutdown signal received, draining")

    shutdownCtx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
    defer cancel()

    if err := srv.Shutdown(shutdownCtx); err != nil {
        slog.Error("graceful shutdown failed, forcing close", "err", err)
        _ = srv.Close()
    }

    slog.Info("shutdown complete")
}

That is the whole pattern. A few details are load-bearing:

signal.NotifyContext instead of a channel. Since Go 1.16 this gives you a context.Context that cancels on the listed signals, which composes with everything else that already takes a context. If contexts and cancellation are new to you, understanding Golang context is the background reading.

Calling stop() after the first signal. It restores the default signal behaviour, so an impatient operator pressing Ctrl-C a second time gets an immediate exit instead of being ignored.

A fresh context for Shutdown. Deriving it from ctx would be a bug: ctx is already cancelled, so Shutdown would return instantly and drain nothing.

Checking for ErrServerClosed. ListenAndServe returns it on a clean shutdown. Treating that as a failure produces a scary log line on every normal deploy.

What Shutdown Does and Does Not Do

Server.Shutdown closes all open listeners, closes idle connections, and then waits for active ones to become idle. It returns when everything is drained or when its context expires — whichever comes first.

What it does not cover:

• Hijacked connections, including WebSockets. Shutdown does not wait for them, and it does not close them. You have to track and close them yourself.
• Background goroutines you started outside the request path. Nothing knows about them.
• Long-polling or streaming responses. These are “active” for as long as they stream, so they will hold the drain open until your timeout fires.

For WebSockets, the usual approach is to register a callback that broadcasts a close frame:

srv.RegisterOnShutdown(func() {
    hub.CloseAll(websocket.CloseServiceRestart, "server restarting")
})

RegisterOnShutdown callbacks run in their own goroutines as soon as Shutdown starts, so they get the whole drain window to do their work.

Draining Background Workers Too

Most real services do more than serve HTTP. If you have consumers, cron loops, or a queue like the one in my simple queue implementation, they need to finish too. errgroup keeps this readable:

import "golang.org/x/sync/errgroup"

func run(ctx context.Context) error {
    srv := &http.Server{Addr: ":8080", Handler: newRouter()}
    queue := NewQueue()

    g, gCtx := errgroup.WithContext(ctx)

    // 1. Serve HTTP.
    g.Go(func() error {
        if err := srv.ListenAndServe(); !errors.Is(err, http.ErrServerClosed) {
            return fmt.Errorf("http server: %w", err)
        }
        return nil
    })

    // 2. Consume the queue until the group context is cancelled.
    g.Go(func() error {
        return queue.Consume(gCtx)
    })

    // 3. When anything cancels gCtx — a signal, or a failure in another
    //    goroutine — drain the HTTP server.
    g.Go(func() error {
        <-gCtx.Done()

        shutdownCtx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
        defer cancel()

        return srv.Shutdown(shutdownCtx)
    })

    return g.Wait()
}

func main() {
    ctx, stop := signal.NotifyContext(context.Background(),
        os.Interrupt, syscall.SIGTERM)
    defer stop()

    if err := run(ctx); err != nil {
        slog.Error("service stopped", "err", err)
        os.Exit(1)
    }
    slog.Info("service stopped cleanly")
}

The nice property here is that failure propagates in both directions. A signal drains the HTTP server; a fatal error in the queue consumer also drains the HTTP server, because errgroup.WithContext cancels gCtx as soon as any goroutine returns an error.

The order of shutdown matters, and it is the reverse of startup: stop accepting work, finish what you have, then close the things that work depends on. Closing your database pool before draining HTTP guarantees a burst of errors from requests that were nearly done.

// After g.Wait() returns, nothing is still using these.
defer db.Close()
defer redis.Close()

The Load Balancer Problem

Here is the part that surprises people: even a perfectly graceful process can drop requests.

Between the moment your pod receives SIGTERM and the moment the load balancer stops sending it traffic, there is a gap. Endpoint updates propagate asynchronously — through the API server, to kube-proxy or an ingress controller, and finally to the actual routing table. During that gap the balancer is still sending new connections to a server that has already closed its listener. Those connections are refused.

The fix is to keep serving for a few seconds after the signal arrives:

<-ctx.Done()
slog.Info("signal received, waiting for load balancer to deregister")

// Keep serving while the endpoint removal propagates.
time.Sleep(5 * time.Second)

shutdownCtx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
defer cancel()
_ = srv.Shutdown(shutdownCtx)

It feels wrong to sleep on purpose, but it is the standard remedy, and Kubernetes has a hook for exactly this so you do not need it in your code:

lifecycle:
  preStop:
    exec:
      command: ["/bin/sh", "-c", "sleep 5"]
terminationGracePeriodSeconds: 45

preStop runs before SIGTERM is sent, while the pod is already being removed from the endpoints list. By the time your process sees the signal, traffic has stopped arriving.

Whichever way you do it, keep the arithmetic straight:

preStop sleep (5s) + drain timeout (20s) + close time (2s) < terminationGracePeriodSeconds (45s)

If the total exceeds the grace period, you get SIGKILL mid-drain and you are back where you started. Give yourself real headroom — the default grace period is 30 seconds, which is not much once a slow request is in flight.

A readiness probe that starts failing on SIGTERM achieves the same thing more precisely:

var ready atomic.Bool

func init() { ready.Store(true) }

// /readyz
func readyz(w http.ResponseWriter, r *http.Request) {
    if !ready.Load() {
        http.Error(w, "shutting down", http.StatusServiceUnavailable)
        return
    }
    w.WriteHeader(http.StatusOK)
}

// On signal, before draining:
ready.Store(false)

Keep /healthz (liveness) returning 200 the whole time — if liveness fails during shutdown, the kubelet may kill the container instead of letting it drain.

Docker Gotchas

Two container-level mistakes will silently defeat everything above.

Shell-form CMD makes your process PID 2. Written as CMD ./server, Docker runs /bin/sh -c ./server. The shell is PID 1, receives SIGTERM, and does not forward it. Your server never hears a thing.

# Wrong — signals stop at the shell
CMD ./server

# Right — exec form, your binary is PID 1
CMD ["./server"]

docker stop waits 10 seconds by default. If your drain window is 20 seconds, you will be killed halfway through. Raise it: docker stop -t 45, or stop_grace_period: 45s in Compose.

Verifying It Works

Do not take it on faith — this is easy to test. Add a slow endpoint, start a request, and signal the process mid-flight:

mux.HandleFunc("/slow", func(w http.ResponseWriter, r *http.Request) {
    select {
    case <-time.After(10 * time.Second):
        w.Write([]byte("finished\n"))
    case <-r.Context().Done():
        // The client gave up; Shutdown does not cancel request contexts.
        return
    }
})

./server &
curl -s localhost:8080/slow &     # starts a 10s request
sleep 1
kill -TERM %1                     # signal while it is in flight

A correct implementation prints finished after ten seconds and then exits. A broken one prints nothing and the curl reports a reset connection.

For the same check under real traffic, point a load test at the service and restart it mid-run — the technique from an easy way to load test your web apps works well here. With graceful shutdown in place your error count during a restart should be exactly zero; without it, you will see the exact number of requests that were in flight.

Note what Shutdown does not do: it does not cancel r.Context() for in-flight requests. That is deliberate — the request should be allowed to complete. It also means a handler with no timeout of its own can hold the drain open until your shutdown context expires, which is why the WriteTimeout in the first example matters.

Checklist

• signal.NotifyContext for SIGINT and SIGTERM.
• srv.Shutdown with its own fresh, bounded context.
• errors.Is(err, http.ErrServerClosed) treated as success.
• Background workers cancelled through the same context, drained before dependencies close.
• Dependencies closed last, in reverse order of startup.
• Readiness probe flipped to failing before the drain begins.
• preStop hook or a deliberate sleep to cover load balancer propagation.
• Grace period comfortably larger than the sum of your timeouts.
• Exec-form CMD in the Dockerfile.
• A test that proves an in-flight request survives a SIGTERM.

Conclusion

Graceful shutdown is one of those features nobody notices when it works — which is precisely the point. Twenty lines in main, a couple of timeouts that add up correctly, and a container that actually forwards signals will turn every deploy from a small burst of errors into a non-event. It is the cheapest reliability win available to a Go service, and worth adding before the next release rather than after the next incident.

Why Structured Logs Beat Formatted Strings

Here is a line the old log package might produce:

2026/08/04 10:15:02 user 42 checkout failed after 1.2s: payment declined

It reads fine. Now try answering “how many checkouts failed for users on the EU cluster last Tuesday between 14:00 and 15:00?” You are writing a regular expression.

The same event as structured data:

{"time":"2026-08-04T10:15:02.113Z","level":"ERROR","msg":"checkout failed",
 "user_id":42,"duration_ms":1204,"reason":"payment declined","cluster":"eu"}

Now it is a query. Every log aggregator — Loki, Elasticsearch, CloudWatch, BigQuery — indexes those fields directly. The point of structured logging is not prettier output; it is that your logs become a queryable dataset.

The Smallest Useful Setup

package main

import (
    "log/slog"
    "os"
)

func main() {
    logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        Level: slog.LevelInfo,
    }))

    // Make it the package-level default so slog.Info et al. use it too.
    slog.SetDefault(logger)

    slog.Info("service started", "port", 8080, "env", "production")
}

Output:

{"time":"2026-08-04T10:15:02.09Z","level":"INFO","msg":"service started","port":8080,"env":"production"}

The variadic arguments are alternating keys and values. If you prefer something the compiler can check, use typed attributes instead:

slog.Info("service started",
    slog.Int("port", 8080),
    slog.String("env", "production"),
)

Both forms are fine, and you can mix them. The typed form costs a little more typing and saves you from the classic odd-number-of-arguments bug, where a stray value ends up under the key !BADKEY.

For local development, swap the handler and keep everything else:

var handler slog.Handler
if os.Getenv("ENV") == "development" {
    handler = slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelDebug})
} else {
    handler = slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo})
}
slog.SetDefault(slog.New(handler))

Levels, and Changing Them Without a Redeploy

slog has four built-in levels — Debug (-4), Info (0), Warn (4), Error (8) — as plain integers, so you can define your own in between if you really need to.

The more useful trick is a LevelVar, which lets you change the level at runtime:

var logLevel = new(slog.LevelVar) // defaults to Info

func main() {
    slog.SetDefault(slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        Level: logLevel,
    })))

    // Flip to debug on demand — from a signal handler, an admin endpoint,
    // or a config watcher.
    http.HandleFunc("/debug/level", func(w http.ResponseWriter, r *http.Request) {
        var l slog.Level
        if err := l.UnmarshalText([]byte(r.FormValue("level"))); err != nil {
            http.Error(w, "bad level", http.StatusBadRequest)
            return
        }
        logLevel.Set(l)
        slog.Warn("log level changed", "level", l)
    })
}

Being able to turn on debug logging for two minutes on a misbehaving pod, without a deploy, has saved me more time than any other logging feature. Put that endpoint behind authentication — the router access permission patterns I wrote about earlier work well for exactly this kind of internal route.

Attaching Context With With

logger.With returns a new logger that carries the given attributes on every subsequent call. This is how you stop repeating yourself:

// Once, at construction:
type Worker struct {
    log *slog.Logger
}

func NewWorker(id int, queue string) *Worker {
    return &Worker{
        log: slog.Default().With("worker_id", id, "queue", queue),
    }
}

func (w *Worker) process(job Job) {
    // Every line from this worker carries worker_id and queue automatically.
    w.log.Info("job started", "job_id", job.ID)
    // ...
    w.log.Info("job finished", "job_id", job.ID, "duration_ms", 42)
}

With does the attribute formatting work once, at call time, rather than on every log line — so a long-lived logger built with With is cheaper than passing the same attributes repeatedly.

Use WithGroup when you want to namespace a block of fields:

log := slog.Default().WithGroup("http")
log.Info("request", "method", "GET", "path", "/users")
// {"level":"INFO","msg":"request","http":{"method":"GET","path":"/users"}}

Or group inline, for one call:

slog.Info("upstream call",
    slog.String("service", "billing"),
    slog.Group("response",
        slog.Int("status", 502),
        slog.Duration("latency", 1200*time.Millisecond),
    ),
)

Request-Scoped Logging

The pattern that pays off most in a web service: put a logger carrying the request ID into the request context, then let every layer below pull it out. If you have not used context.Context for this kind of request-scoped data before, understanding Golang context covers the rules — including why the key must be an unexported type.

package logging

import (
    "context"
    "log/slog"
)

type ctxKey struct{}

// Into returns a copy of ctx carrying logger.
func Into(ctx context.Context, logger *slog.Logger) context.Context {
    return context.WithValue(ctx, ctxKey{}, logger)
}

// From returns the logger stored in ctx, or the default logger.
func From(ctx context.Context) *slog.Logger {
    if l, ok := ctx.Value(ctxKey{}).(*slog.Logger); ok {
        return l
    }
    return slog.Default()
}

The middleware that fills it in — a close cousin of the handler-wrapping in my Go middleware example:

func Middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        requestID := r.Header.Get("X-Request-Id")
        if requestID == "" {
            requestID = uuid.NewString()
        }

        log := slog.Default().With(
            "request_id", requestID,
            "method", r.Method,
            "path", r.URL.Path,
        )

        start := time.Now()
        rec := &statusRecorder{ResponseWriter: w, status: http.StatusOK}

        next.ServeHTTP(rec, r.WithContext(logging.Into(r.Context(), log)))

        log.Info("request completed",
            "status", rec.status,
            "duration_ms", time.Since(start).Milliseconds(),
        )
    })
}

// statusRecorder remembers the status code written by the handler.
type statusRecorder struct {
    http.ResponseWriter
    status int
}

func (r *statusRecorder) WriteHeader(code int) {
    r.status = code
    r.ResponseWriter.WriteHeader(code)
}

Now any function that already takes a context.Context can log with full request context and no extra parameters:

func (s *Store) User(ctx context.Context, id int64) (*User, error) {
    logging.From(ctx).Debug("loading user", "user_id", id)
    // ...
}

Every line from that request — across every layer — shares a request_id. Tracing one user’s bad afternoon becomes a single filter in your log viewer.

Redacting Secrets With ReplaceAttr

HandlerOptions.ReplaceAttr runs on every attribute before it is written. It is the right place to enforce policy centrally instead of trusting each call site.

var sensitive = map[string]bool{
    "password": true, "token": true, "authorization": true,
    "api_key": true, "secret": true, "set-cookie": true,
}

handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
    Level:     slog.LevelInfo,
    AddSource: true, // include file:line — useful for errors
    ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
        if sensitive[strings.ToLower(a.Key)] {
            return slog.String(a.Key, "[REDACTED]")
        }
        // Rename "time" to "timestamp" to match the rest of our pipeline.
        if a.Key == slog.TimeKey && len(groups) == 0 {
            a.Key = "timestamp"
        }
        return a
    },
})

For types you control, implementing LogValuer is even better — the value redacts itself wherever it is logged:

type Password string

// LogValue implements slog.LogValuer so a Password never reaches a log sink.
func (Password) LogValue() slog.Value {
    return slog.StringValue("[REDACTED]")
}

slog.Info("login attempt", "user", "alex", "password", Password("hunter2"))
// {"level":"INFO","msg":"login attempt","user":"alex","password":"[REDACTED]"}

LogValuer is also how you log a struct compactly. Give your User type a LogValue that returns a group with just the ID and role, and you never accidentally dump an entire record — with its email address and hashed password — into a log line.

Logging Errors Properly

Log the error value, not a formatted string, and let the handler decide how to render it:

if err != nil {
    slog.Error("checkout failed", "err", err, "user_id", userID)
    return fmt.Errorf("checkout: %w", err)
}

Two habits worth keeping:

• Log once, at the boundary. If you log here and return the error, every caller up the stack logs it again. That is the same rule I covered in error handling in Go, and slog does not change it.
• Do not log context.Canceled as an error. A user closing a tab is not an incident.

switch {
case errors.Is(err, context.Canceled):
    slog.Debug("client disconnected", "path", r.URL.Path)
case err != nil:
    slog.Error("request failed", "err", err, "path", r.URL.Path)
}

Bridging Libraries That Use the Old log Package

Dependencies still writing to the standard log package do not have to break your JSON output:

// Route everything from the standard logger through slog at Info level.
slog.SetLogLoggerLevel(slog.LevelInfo)

// Or hand a specific component its own *log.Logger backed by slog.
srv := &http.Server{
    Addr:     ":8080",
    Handler:  mux,
    ErrorLog: slog.NewLogLogger(slog.Default().Handler(), slog.LevelError),
}

That second line is worth adding to every server you write — http.Server logs connection errors through ErrorLog, and by default they land on stderr as unstructured text that your aggregator will not parse.

Performance Notes

slog is designed so the common path allocates very little, but a few habits matter:

• Guard genuinely expensive debug work behind Enabled:

  if slog.Default().Enabled(ctx, slog.LevelDebug) {
      slog.Debug("payload", "body", expensiveDump(req))
  }
  

• Prefer LogAttrs in hot paths — it takes typed attributes and skips the any boxing:

  slog.LogAttrs(ctx, slog.LevelInfo, "cache hit",
      slog.String("key", key),
      slog.Int("size", len(val)),
  )
  

• Build the per-request logger once with With, not per log line.

None of this matters at ten requests per second. All of it matters in a hot loop — the same way caching with Ristretto only pays off once you are actually calling the expensive thing often.

Checklist

• One handler, configured once in main, installed with slog.SetDefault.
• JSON in production, text locally.
• A LevelVar so you can raise verbosity without a redeploy.
• A request-scoped logger in the context, carrying the request ID.
• ReplaceAttr or LogValuer for anything secret.
• Errors logged once, at the boundary, as values.
• http.Server.ErrorLog wired through slog.

Conclusion

log/slog removed the last dependency I used to add reflexively to every new Go service. It is fast enough, it is in the standard library, and its handler interface means you can change output format or destination without touching a single call site. If you are still logging with fmt.Sprintf, the migration is mostly mechanical — and the first time you filter a week of logs by request_id, you will not want to go back.

It pays off especially well for anything token-billed, where a handful of numeric fields per call is the only record of what a feature costs — calling an LLM from Go covers which ones to log.

In this article we will demystify the context package, walk through common use-cases, and share production-tested best practices.

Why Context Exists

Go’s lightweight goroutines make it trivial to spin up concurrent work, but once you have hundreds (or thousands) of goroutines you need a structured way to:

1. Cancel unfinished work when a client disconnects or a parent task ends.
2. Enforce upper time bounds to prevent runaway operations.
3. Propagate deadlines deep into the call graph.
4. Attach request-level metadata (trace IDs, auth tokens, etc.) without polluting function signatures.

The context package solves these problems with two core ideas:

• Cancellation propagation via Done() channels.
• Immutable trees—each derived context references its parent, forming a hierarchy that can be cancelled from the root.

Creating and Cancelling Contexts

The building blocks are context.Background() (or context.TODO()), context.WithCancel, context.WithTimeout, and context.WithDeadline.

package main

import (
    "context"
    "fmt"
    "time"
)

func main() {
    // Start with a root context
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel() // always release resources

    // Fire off a worker goroutine
    go func() {
        select {
        case <-ctx.Done():
            fmt.Println("worker cancelled:", ctx.Err())
            return
        }
    }()

    // Simulate some condition that requires cancellation
    time.Sleep(500 * time.Millisecond)
    cancel()

    time.Sleep(100 * time.Millisecond)
}

Running this prints:

worker cancelled: context canceled

Timeout Helper

context.WithTimeout wraps WithCancel plus a timer:

ctx, cancel := context.WithTimeout(parent, 2*time.Second)
// After 2s: ctx.Err() == context.DeadlineExceeded

Remember to always call the returned cancel—even when the timeout expires—so the timer’s internal resources are freed.

Passing Context Down the Call Stack

The first parameter of every context-aware function should be ctx context.Context:

func fetch(ctx context.Context, url string) ([]byte, error) {
    req, _ := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    return io.ReadAll(resp.Body)
}

When ctx is cancelled upstream, http.Client aborts the request automatically.

Deadlines vs. Timeouts

A deadline is an absolute moment (2025-06-16T14:05:00+02:00) while a timeout is a relative duration (5s). Internally both are implemented with WithDeadline, but modelling them correctly communicates intent:

deadline := time.Now().Add(5 * time.Second)
ctx, cancel := context.WithDeadline(parent, deadline)

Storing Values in Context

context.WithValue allows passing request-scoped data without modifying every function signature. Use it sparingly:

// Key type prevents collisions
 type key string
 const traceIDKey key = "traceID"

 ctx := context.WithValue(parent, traceIDKey, "abc-123")

 // Downstream retrieval
 if v := ctx.Value(traceIDKey); v != nil {
     traceID := v.(string)
     log.Println("traceID:", traceID)
 }

Guidelines

1. Only store immutable, request-specific data (IDs, auth tokens).
2. Never store optional params that belong in function arguments.
3. Define unexported key types to avoid collisions across packages.

Common Pitfalls

End-to-End Example: HTTP Server with Timeouts

package main

import (
    "context"
    "fmt"
    "net/http"
    "time"
)

func main() {
    srv := &http.Server{
        Addr:         ":8080",
        ReadTimeout:  3 * time.Second,
        WriteTimeout: 5 * time.Second,
        Handler:      http.HandlerFunc(handler),
    }

    // Shutdown gracefully on interrupt
    go func() {
        <-time.After(10 * time.Second) // Simulate interrupt
        ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
        defer cancel()
        _ = srv.Shutdown(ctx)
    }()

    fmt.Println("Serving on :8080")
    if err := srv.ListenAndServe(); err != http.ErrServerClosed {
        panic(err)
    }
    fmt.Println("Server gracefully stopped")
}

func handler(w http.ResponseWriter, r *http.Request) {
    // r.Context() inherits deadlines from the server
    select {
    case <-time.After(2 * time.Second):
        w.Write([]byte("done"))
    case <-r.Context().Done():
        http.Error(w, "request cancelled", http.StatusRequestTimeout)
    }
}

Best Practices Checklist

• Pass context.Context as the first parameter; never embed it in structs.
• Do not store contexts—pass them along the call chain.
• Cancel contexts to free resources early.
• Use short-lived timeouts close to I/O boundaries rather than a single large timeout at the root.
• Keep functions context-aware; return early on <-ctx.Done().

Conclusion

The golang context package brings order to concurrent Go programs by standardising how we propagate cancellation and deadlines. Mastering it unlocks more reliable, resource-efficient applications.

Context shows up everywhere once you start looking for it. Three follow-ups that use it heavily: graceful shutdown in Go web services, worker pools with errgroup, and a simple queue implementation. It also turns up in every LLM call you will ever write, since those are slow, cancellable and worth a deadline — see calling an LLM from Go.