Stern Logs

stern

stern tails logs from many pods and many containers at once, selected by a regex or a Kubernetes resource, with automatic pickup of new pods and colorized per-pod output.

Iron Law

In an agent/non-interactive context, every stern invocation carries --no-follow.

Without it stern streams forever and never exits — the tool call blocks until the harness timeout, and the partial output may be discarded. The only exception: the user explicitly asked to watch a live stream, and it runs as a background command with a stated stop condition.

The second half of the law: bound the volume. The defaults are --since 48h and --tail -1 (every line ever retained), multiplied by every matching pod. Always narrow at least one of --tail / --since — and both once the query spans more than a handful of containers, since they are what truncates each stream. Narrowing which containers are read at all (-E, --exclude-pod, -l, a tighter query) saves more and costs nothing; line filters save neither.

Rationalization table

Every one of these will occur to you mid-task. All of them are wrong.

The load-bearing test is not "is streaming reasonable here?" but "who reads the output?" If the answer is you, in this tool call, then --no-follow.

The default command shape

stern <query> -n <namespace> --no-follow --tail 50 --since 1h --color never --only-log-lines

Keep the status lines (i.e. omit --only-log-lines) when you need to know which pods were even found — that is often the actual answer.

If the task already has a familiar shape — a crash loop, hunting one error across a namespace, getting output in chronological order, replaying a local log file — take the worked command from references/recipes.md instead of composing flags from scratch.

Selecting what to read

The positional argument is a regex on pod names, unless it has the form <resource>/<name>, which is an exact resource lookup:

stern . --no-follow            # every pod in the namespace (regex "." matches all)
stern 'web-\w' --no-follow     # web-backend, web-frontend — but not web-123
stern deploy/nginx --no-follow # all pods belonging to that Deployment
stern svc/api --no-follow      # all pods behind that Service

Supported resources (with aliases): pod/po, replicationcontroller/rc, service/svc, daemonset/ds, deployment/deploy, replicaset/rs, statefulset/sts, job. Plural forms work too (deployments/nginx).

Narrow further with:

Since Kubernetes 1.28 a native sidecar is an init container with restartPolicy: Always, so --init-containers=false on a mesh-injected pod removes the proxy too. That is usually what you want — but the proxy's access logs carry x-request-id, which is what makes following one request across services possible. Drop istio-init alone with -E istio-init when you need to keep it.

That table is the working subset. When you need a flag that is not in it, an exact default, or the config file that may silently be changing those defaults, read references/flags.md — guessing a flag name costs a failed invocation.

--include / -i and --exclude / -e filter log lines (regex, repeatable) — prefer them over piping to grep, because they apply before the lines are formatted. They do not make the query cheaper: filtering happens locally on lines already received. To spend less, cut containers with the selection flags above, or truncate with --tail/--since.

stern deploy/api --no-follow --tail 200 -i 'ERROR|panic' -e 'health.?check'

Reading the result correctly

• Empty output is not an error. A query matching no pods exits 0 and prints nothing. Verify with kubectl get pods -n <ns> before concluding "there are no errors".
• Lines from different pods interleave in arrival order, not timestamp order. Piping the default output to sort sorts by pod name, because that is what the default template leads with. Either serialize the reads, or put the timestamp first with a template:

  stern deploy/api --no-follow --max-log-requests 1 --tail 100   # pod by pod, in order
  
  set -o pipefail                                                # sort exits 0 on empty input too
  stern . -A --no-follow --since 10m --only-log-lines --color never -t \
    --template='{{.Message}}  @{{.PodName}}/{{.ContainerName}}{{"\n"}}' | sort
  

  That works because -t prefixes the timestamp into .Message — which is also why -t breaks parseJSON templates and -o raw | jq. There is no separate timestamp field.
• --max-log-requests never silently drops pods. With --no-follow (default 5) it is a concurrency limit: every matching container is still read, just fewer at a time, so the output is complete and only slower. Without --no-follow (default 50) exceeding it is a hard error that stops stern with a message naming the flag. The limit counts containers, not pods — one 3-container pod trips --max-log-requests 1. Raise it to watch more pods, never because you suspect missing output, and not to go faster: wall clock is set by --qps, not by this flag.

Machine-readable output

# no pipe: stern's own exit status is the answer
stern deploy/api --no-follow --tail 100 -o json --only-log-lines

# piped: pipefail belongs in the command, not in a footnote.
# -i '^\s*\{' keeps plain-text framework lines away from jq
set -o pipefail
stern deploy/api --no-follow --tail 100 -o raw --only-log-lines -i '^\s*\{' | jq

Three things in that snippet, each preventing a different wrong answer:

• --only-log-lines, not a redirect. The + pod › container attach lines go to stderr, so 2>&1 | jq feeds jq a non-JSON line and the pipeline aborts to nothing; 2>/dev/null avoids that but throws away stern's real errors (RBAC forbidden, a bad --context) along with the noise. --only-log-lines stops the status lines being printed at all and leaves errors on stderr.
• set -o pipefail. jq exits 0 on empty input, so without it the pipeline reports success even when stern failed. It is portable — prefer it. Where you cannot set it, check the first command's status rather than $?: ${PIPESTATUS[0]} in bash, ${pipestatus[1]} in zsh (lowercase, and 1-indexed). Using the bash spelling under zsh expands to an empty string, which reads as "did not fail" — the exact failure this bullet exists to prevent, on the shell macOS defaults to.
• -i '^\s*\{' with -o raw. -o raw passes the application's own line through, and real services mix formats — framework and stdlib lines are plain text alongside the JSON logger. jq aborts on the first one, prints nothing and exits 5, which pipefail turns into a failed pipeline for perfectly healthy logs. -o json needs no guard: that envelope is always valid JSON. Keep the \s* — a bare ^\{ drops an indented record silently at exit 0. Guarding on the jq side instead takes two filters, jq -R 'fromjson? | objects | …': ? guards only fromjson, so without objects a top-level array or scalar parses, reaches the field filter and raises a per-record error that pipefail cannot see — jq reports only the last input's status.

For the -o json field names, the other predefined outputs, and --template for reshaping JSON application logs into something readable, see references/templates.md.

Preflight

1. command -v stern — if missing, brew install stern (macOS/Linux) or kubectl krew install stern; kubectl logs is the fallback for a single pod.
2. Know which cluster you are about to read: kubectl config current-context. Confirm with the user before pulling logs from an unfamiliar or production-looking context, and remember that log content may contain secrets — quote selectively rather than dumping it wholesale.
3. stern honours $KUBECONFIG; --kubeconfig and --context override it.

Gotchas

Each reference is linked above from the point where it becomes the right thing to read: recipes.md for worked commands, flags.md for the complete flag set and config file, templates.md for output formatting.