stern

Fork of discontinued wercker/stern

Stern allows you to tail multiple pods on Kubernetes and multiple containers within the pod. Each result is color coded for quicker debugging.

The query is a regular expression or a Kubernetes resource in the form / so the pod name can easily be filtered and you don't need to specify the exact id (for instance omitting the deployment id). If a pod is deleted it gets removed from tail and if a new pod is added it automatically gets tailed.

When a pod contains multiple containers Stern can tail all of them too without having to do this manually for each one. Simply specify the container flag to limit what containers to show. By default all containers are listened to.

Installation

Download binary

Download a binary release

Build from source

go install github.com/stern/stern@latest

asdf (Linux/macOS)

If you use asdf, you can install like this:

asdf plugin add stern
asdf install stern latest

Homebrew (Linux/macOS)

If you use Homebrew, you can install like this:

brew install stern

Krew (Linux/macOS/Windows)

If you use Krew which is the package manager for kubectl plugins, you can install like this:

kubectl krew install stern

WinGet (Windows)

If you're running on Windows, usually the actual best way is to use WinGet to install which is Windows' built-in package manager, you can install like this:

winget install stern.stern

Usage

stern pod-query [flags]

The pod-query is a regular expression or a Kubernetes resource in the form /.

The query is a regular expression when it is not a Kubernetes resource, so you could provide "web-\w" to tail web-backend and web-frontend pods but not web-123.

When the query is in the form / (exact match), you can select all pods belonging to the specified Kubernetes resource, such as deployment/nginx. Supported Kubernetes resources are pod, replicationcontroller, service, daemonset, deployment, replicaset, statefulset and job.

cli flags

See stern --help for details

Stern will use the $KUBECONFIG environment variable if set. If both the environment variable and --kubeconfig flag are passed the cli flag will be used.

config file

You can use the config file to change the default values of stern options. The default config file path is ~/.config/stern/config.yaml.

# <flag name>: <value>
tail: 10
max-log-requests: 999
timestamps: short

You can change the config file path with --config flag or STERNCONFIG environment variable.

templates

stern supports outputting custom log messages. There are a few predefined templates which you can use by specifying the --output flag:

It accepts a custom template through the --template flag, which will be compiled to a Go template and then used for every log message. This Go template will receive the following struct:

The following functions are available within the template (besides the builtin functions):

Log level verbosity

You can configure the log level verbosity by the --verbosity flag. It is useful when you want to know how stern interacts with a Kubernetes API server in troubleshooting.

Increasing the verbosity increases the number of logs. --verbosity 6 would be a good starting point.

Max log requests

Stern has the maximum number of concurrent logs to request to prevent unintentional load to a cluster. The number can be configured by the --max-log-requests flag.

The behavior and the default are different depending on the presence of the --no-follow flag.

The combination of --max-log-requests 1 and --no-follow will be helpful if you want to show logs in order.

Customize highlight colors

You can configure highlight colors for pods and containers in the config file using a comma-separated list of SGR (Select Graphic Rendition) sequences, as shown below. If you omit container-colors, the pod colors will be used as container colors as well.

# Green, Yellow, Blue, Magenta, Cyan, White
pod-colors: "32,33,34,35,36,37"

# Colors with underline (4)
# If empty, the pod colors will be used as container colors
container-colors: "32;4,33;4,34;4,35;4,36;4,37;4"

This format enables the use of various attributes, such as underline, background colors, 8-bit colors, and 24-bit colors, if your terminal supports them.

The equivalent flags --pod-colors and --container-colors are also available. The following command applies 24-bit colors using the --pod-colors flag.

# Monokai theme
podColors="38;2;255;97;136,38;2;169;220;118,38;2;255;216;102,38;2;120;220;232,38;2;171;157;242"
stern --pod-colors "$podColors" deploy/app

Examples:

Tail all logs from all namespaces

stern . --all-namespaces

Tail the kube-system namespace without printing any prior logs

stern . -n kube-system --tail 0

Tail the gateway container running inside of the envvars pod on staging

stern envvars --context staging --container gateway

Tail the staging namespace excluding logs from istio-proxy container

stern -n staging --exclude-container istio-proxy .

Tail the kube-system namespace excluding logs from kube-apiserver pod

stern -n kube-system --exclude-pod kube-apiserver .

Show auth activity from 15min ago with timestamps

stern auth -t --since 15m

Show all logs of the last 5min by time, sorted by time

stern --since=5m --no-follow --only-log-lines -A -t . | sort -k4

Show auth activity with timestamps in specific timezone (default is your local timezone)

stern auth -t --timezone Asia/Tokyo

Follow the development of some-new-feature in minikube

stern some-new-feature --context minikube

View pods from another namespace

stern kubernetes-dashboard --namespace kube-system

Tail the pods filtered by run=nginx label selector across all namespaces

stern --all-namespaces -l run=nginx

Follow the frontend pods in canary release

stern frontend --selector release=canary

Tail the pods on kind-control-plane node across all namespaces

stern --all-namespaces --field-selector spec.nodeName=kind-control-plane

Tail the pods created by deployment/nginx

stern deployment/nginx

Pipe the log message to jq:

stern backend -o json | jq .

Only output the log message itself:

stern backend -o raw

Output using a custom template:

stern --template '{{printf "%s (%s/%s/%s/%s)\n" .Message .NodeName .Namespace .PodName .ContainerName}}' backend

Output using a custom template with stern-provided colors:

stern --template '{{.Message}} ({{.Namespace}}/{{color .PodColor .PodName}}/{{color .ContainerColor .ContainerName}}){{"\n"}}' backend

Output using a custom template with parseJSON:

stern --template='{{.PodName}}/{{.ContainerName}} {{with $d := .Message | parseJSON}}[{{$d.level}}] {{$d.message}}{{end}}{{"\n"}}' backend

Output using a custom template that tries to parse JSON or fallbacks to raw format:

stern --template='{{.PodName}}/{{.ContainerName}} {{ with $msg := .Message | tryParseJSON }}[{{ colorGreen (toRFC3339Nano $msg.ts) }}] {{ levelColor $msg.level }} ({{ colorCyan $msg.caller }}) {{ $msg.msg }}{{ else }} {{ .Message }} {{ end }}{{"\n"}}' backend

Pretty print JSON (if it is JSON) and output it:

# Will try to parse .Message as JSON and pretty print it, if not json will output as is
stern --template='{{ .Message | prettyJSON }}{{"\n"}}' backend
# Or with parsed json, will drop non-json logs because of `with`
stern --template='{{ with $msg := .Message | tryParseJSON }}{{ prettyJSON $msg }}{{"\n"}}{{end}}' backend

Extract fields from JSON, including nested fields via dot notation:

# Given a message like {"python": {"levelname": "INFO", "module": "router"}}
stern --template='{{ levelColor (extractJSONParts .Message "python.levelname") }} {{ extractJSONParts .Message "python.module" }}{{"\n"}}' backend

Load custom template from file:

stern --template-file=~/.stern.tpl backend

Trigger the interactive prompt to select an 'app.kubernetes.io/instance' label value:

stern -p

Output log lines only:

stern . --only-log-lines

Read from stdin:

stern --stdin < service.log

Only display logs for pods that are not ready:

stern . --condition=ready=false --tail=0

Completion

Stern supports command-line auto completion for bash, zsh or fish. stern --completion=(bash|zsh|fish) outputs the shell completion code which work by being evaluated in .bashrc, etc for the specified shell. In addition, Stern supports dynamic completion for --namespace, --context, --node, a resource query in the form /, and flags with pre-defined choices.

If you use bash, stern bash completion code depends on the bash-completion. On the macOS, you can install it with homebrew as follows:

# If running Bash 3.2
brew install bash-completion

# or, if running Bash 4.1+
brew install bash-completion@2

Note that bash-completion must be sourced before sourcing the stern bash completion code in .bashrc.

source "$(brew --prefix)/etc/profile.d/bash_completion.sh"
source <(stern --completion=bash)

If installed via Krew, use:

source <(kubectl stern --completion bash)
complete -o default -F __start_stern kubectl stern

If you use zsh, just source the stern zsh completion code in .zshrc.

source <(stern --completion=zsh)

if you use fish shell, just source the stern fish completion code.

stern --completion=fish | source

# To load completions for each session, execute once:
stern --completion=fish >~/.config/fish/completions/stern.fish

Running with container

You can also use stern using a container:

docker run ghcr.io/stern/stern --version

If you are using a minikube cluster, you need to run a container as follows:

docker run --rm -v "$HOME/.minikube:$HOME/.minikube" -v "$HOME/.kube:/$HOME/.kube" -e KUBECONFIG="$HOME/.kube/config" ghcr.io/stern/stern .

You can find image tags in https://github.com/orgs/stern/packages/container/package/stern.

Running in Kubernetes Pods

If you want to use stern in Kubernetes Pods, you need to create the following ClusterRole and bind it to ServiceAccount.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: stern
rules:
- apiGroups: [""]
  resources: ["pods", "pods/log"]
  verbs: ["get", "watch", "list"]

Contributing to this repository

Please see CONTRIBUTING for details.