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 <resource>/<name> 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 <resource>/<name>.

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 <resource>/<name> (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

flag	default	purpose
--all-namespaces, -A	false	If present, tail across all namespaces. A specific namespace is ignored even if specified with --namespace.
--burst	0	Maximum burst for throttle to the Kubernetes API server. Defaults to 0 (use client-go default). Ignored when --qps=-1.
--color	auto	Force set color output. 'auto': colorize if tty attached, 'always': always colorize, 'never': never colorize.
--completion		Output stern command-line completion code for the specified shell. Can be 'bash', 'zsh' or 'fish'.
--condition		The condition to filter on: [condition-name[=condition-value]. The default condition-value is true. Match is case-insensitive. Currently only supported with --tail=0 or --no-follow.
--config	~/.config/stern/config.yaml	Path to the stern config file
--container, -c	.*	Container name when multiple containers in pod. (regular expression)
--container-colors		Specifies the colors used to highlight container names. Use the same format as --pod-colors. Defaults to the values of --pod-colors if omitted, and must match its length.
--container-state	all	Tail containers with state in running, waiting, terminated, or all. 'all' matches all container states. To specify multiple states, repeat this or set comma-separated value.
--context		The name of the kubeconfig context to use
--diff-container, -d	false	Display different colors for different containers.
--ephemeral-containers	true	Include or exclude ephemeral containers.
--exclude, -e	[]	Log lines to exclude. (regular expression)
--exclude-container, -E	[]	Container name to exclude when multiple containers in pod. (regular expression)
--exclude-pod	[]	Pod name to exclude. (regular expression)
--field-selector		Selector (field query) to filter on. If present, default to ".*" for the pod-query.
--highlight, -H	[]	Log lines to highlight. (regular expression)
--include, -i	[]	Log lines to include. (regular expression)
--init-containers	true	Include or exclude init containers.
--kubeconfig		Path to the kubeconfig file to use for CLI requests.
--max-log-requests	-1	Maximum number of concurrent logs to request. Defaults to 50, but 5 when specifying --no-follow
--namespace, -n		Kubernetes namespace to use. Default to namespace configured in kubernetes context. To specify multiple namespaces, repeat this or set comma-separated value.
--no-follow	false	Exit when all logs have been shown.
--node		Node name to filter on.
--only-log-lines	false	Print only log lines
--output, -o	default	Specify predefined template. Currently support: [default, raw, json, extjson, ppextjson]
--pod-colors		Specifies the colors used to highlight pod names. Provide colors as a comma-separated list using SGR (Select Graphic Rendition) sequences, e.g., "91,92,93,94,95,96".
--prompt, -p	false	Toggle interactive prompt for selecting 'app.kubernetes.io/instance' label values.
--qps	0	Maximum QPS to the Kubernetes API server. Defaults to 0 (use client-go default). Use -1 to disable client-side throttling.
--selector, -l		Selector (label query) to filter on. If present, default to ".*" for the pod-query.
--show-hidden-options	false	Print a list of hidden options.
--since, -s	48h0m0s	Return logs newer than a relative duration like 5s, 2m, or 3h.
--stdin	false	Parse logs from stdin. All Kubernetes related flags are ignored when it is set.
--tail	-1	The number of lines from the end of the logs to show. Defaults to -1, showing all logs.
--template		Template to use for log lines, leave empty to use --output flag.
--template-file, -T		Path to template to use for log lines, leave empty to use --output flag. It overrides --template option.
--timestamps, -t		Print timestamps with the specified format. One of 'default' or 'short' in the form '--timestamps=format' ('=' cannot be omitted). If specified but without value, 'default' is used.
--timezone	Local	Set timestamps to specific timezone.
--verbosity	0	Number of the log level verbosity
--version, -v	false	Print the version and exit.

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:

output	description
default	Displays the namespace, pod and container, and decorates it with color depending on --color
raw	Only outputs the log message itself, useful when your logs are json and you want to pipe them to jq
json	Marshals the log struct to json. Useful for programmatic purposes
extjson	Outputs extended JSON with colorized pod/container names
ppextjson	Pretty-prints extended JSON with colorized pod/container names

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:

property	type	description
Message	string	The log message itself
NodeName	string	The node name where the pod is scheduled on
Namespace	string	The namespace of the pod
PodName	string	The name of the pod
ContainerName	string	The name of the container
Labels	map[string]string	The labels of the pod
Annotations	map[string]string	The annotations of the pod

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

func	arguments	description
json	object	Marshal the object and output it as a json text
color	color.Color, string	Wrap the text in color (.ContainerColor and .PodColor provided)
parseJSON	string	Parse string as JSON
tryParseJSON	string	Attempt to parse string as JSON, return nil on failure
extractJSONParts	string, ...string	Parse string as JSON and concatenate the given keys.
tryExtractJSONParts	string, ...string	Attempt to parse string as JSON and concatenate the given keys. , return text on failure
prettyJSON	any	Parse input and emit it as pretty printed JSON, if parse fails output string as is.
toRFC3339Nano	object	Parse timestamp (string, int, json.Number) and output it using RFC3339Nano format
toTimestamp	object, string [, string]	Parse timestamp (string, int, json.Number) and output it using the given layout in the timezone that is optionally given (defaults to UTC).
levelColor	string	Print log level using appropriate color
bunyanLevelColor	string	Print bunyan numeric log level using appropriate color
colorBlack	string	Print text using black color
colorRed	string	Print text using red color