stern

已停止维护的 wercker/stern 的分支

Stern 允许你在 Kubernetes 上同时 tail 多个 Pod 和 Pod 内的多个容器。每个结果都以彩色编码显示，便于更快速地调试。

查询可以是正则表达式或 Kubernetes 资源，形式为 <资源>/<名称>，因此可以轻松过滤 Pod 名称，无需指定确切的 ID（例如省略部署 ID）。如果一个 Pod 被删除，它会从 tail 中移除；如果新增了一个 Pod，它会自动被添加到 tail 中。

当一个 Pod 包含多个容器时，Stern 也可以同时 tail 所有容器，无需为每个容器手动操作。只需指定 container 标志来限制显示哪些容器。默认情况下，会监听所有容器。

安装

下载二进制文件

下载二进制发布版本

从源代码构建

go install github.com/stern/stern@latest

asdf（Linux/macOS）

如果您使用asdf，可以按以下方式安装：

asdf plugin-add stern
asdf install stern latest

Homebrew（Linux/macOS）

如果您使用Homebrew，可以按以下方式安装：

brew install stern

Krew（Linux/macOS/Windows）

如果您使用Krew（kubectl插件的包管理器），可以按以下方式安装：

kubectl krew install stern

用法

stern pod-查询 [标志]

pod-查询是一个正则表达式或以<资源>/<名称>形式的Kubernetes资源。当查询不是Kubernetes资源时，它是一个正则表达式，因此你可以提供"web-\w"来跟踪web-backend和web-frontend的pod，但不包括web-123。当查询以<资源>/<名称>形式（精确匹配）时，你可以选择属于指定Kubernetes资源的所有pod，例如deployment/nginx。支持的Kubernetes资源包括pod、replicationcontroller、service、daemonset、deployment、 replicaset、statefulset和job。

CLI 标志

标志	默认值	用途
`--all-namespaces`, `-A`	`false`	如果存在，则跨所有命名空间追踪日志。即使使用 --namespace 指定了特定命名空间也会被忽略。
`--color`	`auto`	强制设置颜色输出。'auto'：如果连接到终端则着色，'always'：始终着色，'never'：从不着色。
`--completion`		输出指定 shell 的 stern 命令行补全代码。可以是 'bash'、'zsh' 或 'fish'。
`--config`	`~/.config/stern/config.yaml`	stern 配置文件的路径
`--container`, `-c`	`.*`	当 Pod 中有多个容器时的容器名称。（正则表达式）
`--container-colors`		指定用于高亮显示容器名称的颜色。使用与 --pod-colors 相同的格式。如果省略，默认使用 --pod-colors 的值，且必须与其长度匹配。
`--container-state`	`all`	追踪处于运行中、等待中、已终止或所有状态的容器。'all' 匹配所有容器状态。要指定多个状态，请重复此选项或设置逗号分隔的值。
`--context`		要使用的 kubeconfig 上下文的名称
`--diff-container`, `-d`	`false`	为不同的容器显示不同的颜色。
`--ephemeral-containers`	`true`	包含或排除临时容器。
`--exclude`, `-e`	`[]`	要排除的日志行。（正则表达式）
`--exclude-container`, `-E`	`[]`	当 Pod 中有多个容器时要排除的容器名称。（正则表达式）
`--exclude-pod`	`[]`	要排除的 Pod 名称。（正则表达式）
`--field-selector`		用于过滤的选择器（字段查询）。如果存在，则 pod-query 默认为 ".*"。
`--highlight`, `-H`	`[]`	要高亮显示的日志行。（正则表达式）
`--include`, `-i`	`[]`	要包含的日志行。（正则表达式）
`--init-containers`	`true`	包含或排除初始化容器。
`--kubeconfig`		用于 CLI 请求的 kubeconfig 文件路径。
`--max-log-requests`	`-1`	最大并发日志请求数。默认为 50，但在指定 --no-follow 时为 5
`--namespace`, `-n`		要使用的 Kubernetes 命名空间。默认为 Kubernetes 上下文中配置的命名空间。要指定多个命名空间，请重复此选项或设置逗号分隔的值。
`--no-follow`	`false`	显示完所有日志后退出。
`--node`		要过滤的节点名称。
`--only-log-lines`	`false`	仅打印日志行
`--output`, `-o`	`default`	指定预定义模板。当前支持：[default, raw, json, extjson, ppextjson]
`--pod-colors`		指定用于高亮显示 Pod 名称的颜色。提供以逗号分隔的 SGR（选择图形再现）序列列表，例如 "91,92,93,94,95,96"。
`--prompt`, `-p`	`false`	切换交互式提示以选择 'app.kubernetes.io/instance' 标签值。
`--selector`, `-l`		用于过滤的选择器（标签查询）。如果存在，则 pod-query 默认为 ".*"。
`--show-hidden-options`	`false`	打印隐藏选项列表。
`--since`, `-s`	`48h0m0s`	返回相对持续时间内的较新日志，如 5s、2m 或 3h。
`--stdin`	`false`	从标准输入解析日志。设置此选项时，所有与 Kubernetes 相关的标志都将被忽略。
`--tail`	`-1`	从日志末尾显示的行数。默认为 -1，显示所有日志。
`--template`		用于日志行的模板，留空以使用 --output 标志。
`--template-file`, `-T`		用于日志行的模板文件路径，留空以使用 --output 标志。它会覆盖 --template 选项。
`--timestamps`, `-t`		以指定格式打印时间戳。格式为 '--timestamps=format'（'=' 不能省略），可选 'default' 或 'short'。如果指定但没有值，则使用 'default'。
`--timezone`	`Local`	将时间戳设置为特定时区。
`--verbosity`	`0`	日志级别的详细程度
`--version`, `-v`	`false`	打印版本并退出。

详情请参阅 stern --help 如果设置了 $KUBECONFIG 环境变量，Stern 将使用它。如果同时传递了环境变量和 --kubeconfig 标志，将使用 CLI 标志。

配置文件

您可以使用配置文件来更改stern选项的默认值。默认配置文件路径是~/.config/stern/config.yaml。

# <标志名>: <值>
tail: 10
max-log-requests: 999
timestamps: short

您可以使用--config标志或STERNCONFIG环境变量来更改配置文件路径。

模板

stern 支持输出自定义日志消息。有几个预定义的模板可以通过指定 --output 标志来使用：

输出	描述
`default`	显示命名空间、Pod 和容器，并根据 --color 参数用颜色装饰
`raw`	只输出日志消息本身，当日志是 json 格式且你想通过管道传递给 `jq` 时很有用
`json`	将日志结构体转换为 json。用于编程目的

它通过 --template 标志接受自定义模板，该模板将被编译为 Go 模板，然后用于每条日志消息。这个 Go 模板将接收以下结构体：

属性	类型	描述
`Message`	string	日志消息本身
`NodeName`	string	Pod 调度所在的节点名称
`Namespace`	string	Pod 的命名空间
`PodName`	string	Pod 的名称
`ContainerName`	string	容器的名称

模板中可用以下函数（除了内置函数）：

函数	参数	描述
`json`	`object`	将对象序列化并输出为 json 文本
`color`	`color.Color, string`	用颜色包装文本（提供 .ContainerColor 和 .PodColor）
`parseJSON`	`string`	将字符串解析为 JSON
`tryParseJSON`	`string`	尝试将字符串解析为 JSON，失败时返回 nil
`extractJSONParts`	`string, ...string`	将字符串解析为 JSON 并连接给定的键
`tryExtractJSONParts`	`string, ...string`	尝试将字符串解析为 JSON 并连接给定的键，失败时返回文本
`extjson`	`string`	将对象解析为 json 并输出彩色 json
`ppextjson`	`string`	将对象解析为 json 并输出美化的彩色 json
`toRFC3339Nano`	`object`	解析时间戳（字符串、整数、json.Number）并使用 RFC3339Nano 格式输出
`toTimestamp`	`object, string [, string]`	解析时间戳（字符串、整数、json.Number）并使用给定布局在指定时区（默认为 UTC）输出
`levelColor`	`string`	使用适当的颜色打印日志级别
`colorBlack`	`string`	使用黑色打印文本
`colorRed`	`string`	使用红色打印文本
`colorGreen`	`string`	使用绿色打印文本
`colorYellow`	`string`	使用黄色打印文本
`colorBlue`	`string`	使用蓝色打印文本
`colorMagenta`	`string`	使用洋红色打印文本
`colorCyan`	`string`	使用青色打印文本
`colorWhite`	`string`	使用白色打印文本

日志级别详细程度

您可以通过 --verbosity 标志配置日志级别的详细程度。当您想了解 stern 如何与 Kubernetes API 服务器交互以进行故障排除时，这个功能非常有用。增加详细程度会增加日志的数量。--verbosity 6 是一个不错的起始点。

最大日志请求数

Stern 设置了最大并发日志请求数，以防止对集群造成意外负载。

可以通过 --max-log-requests 标志配置此数值。

根据是否使用 --no-follow 标志，其行为和默认值会有所不同。

`--no-follow`	默认值	行为
指定	5	限制并发日志请求数量
未指定	50	达到并发限制时报错退出

如果你想按顺序显示日志，组合使用 --max-log-requests 1 和 --no-follow 会很有帮助。

自定义高亮颜色

你可以在配置文件中使用逗号分隔的SGR（选择图形再现）序列列表来配置Pod和容器的高亮颜色，如下所示。如果省略container-colors，则Pod颜色也将用作容器颜色。

# 绿色、黄色、蓝色、洋红色、青色、白色
pod-colors: "32,33,34,35,36,37"

# 带下划线（4）的颜色
# 如果为空，则Pod颜色将用作容器颜色
container-colors: "32;4,33;4,34;4,35;4,36;4,37;4"

这种格式允许使用各种属性，如下划线、背景颜色、8位颜色和24位颜色（如果你的终端支持）。

等效的标志--pod-colors和--container-colors也可用。以下命令使用--pod-colors标志应用24位颜色。

# Monokai主题
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

示例：

从所有命名空间获取所有日志

stern . --all-namespaces

获取 kube-system 命名空间的日志，不打印任何先前的日志

stern . -n kube-system --tail 0

获取在 staging 环境中运行的 envvars pod 内的 gateway 容器的日志

stern envvars --context staging --container gateway

获取 staging 命名空间的日志，排除 istio-proxy 容器的日志

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

获取 kube-system 命名空间的日志，排除 kube-apiserver pod 的日志

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

显示15分钟前的身份验证活动，并带有时间戳

stern auth -t --since 15m

按时间顺序显示过去5分钟的所有日志，并按时间排序

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

在特定时区显示带有时间戳的身份验证活动（默认为您的本地时区）

stern auth -t --timezone Asia/Tokyo

在 minikube 中跟踪 some-new-feature 的开发

stern some-new-feature --context minikube

查看另一个命名空间中的 pod

stern kubernetes-dashboard --namespace kube-system

在所有命名空间中获取带有 run=nginx 标签选择器的 pod 日志

stern --all-namespaces -l run=nginx

跟踪金丝雀发布中的 frontend pod

stern frontend --selector release=canary

在所有命名空间中获取 kind-control-plane 节点上的 pod 日志

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

获取由 deployment/nginx 创建的 pod 日志

stern deployment/nginx

将日志消息通过管道传输到 jq：

stern backend -o json | jq .

仅输出日志消息本身：

stern backend -o raw

使用自定义模板输出：

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

使用带有 stern 提供的颜色的自定义模板输出：

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

使用带有 parseJSON 的自定义模板输出：

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

使用尝试解析 JSON 或回退到原始格式的自定义模板输出：

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

从文件加载自定义模板：

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

触发交互式提示以选择 'app.kubernetes.io/instance' 标签值：

stern -p

仅输出日志行：

stern . --only-log-lines

从标准输入读取：

stern --stdin < service.log

完成

Stern 支持 bash、zsh 或 fish 的命令行自动完成功能。stern --completion=(bash|zsh|fish) 输出的 shell 完成代码可通过在指定 shell 的 .bashrc 等文件中进行评估来工作。此外，Stern 支持对 --namespace、--context、--node、<resource>/<name> 形式的资源查询以及具有预定义选项的标志进行动态完成。

如果您使用 bash，Stern 的 bash 完成代码依赖于 bash-completion。在 macOS 上，您可以使用 homebrew 安装它，如下所示：

# 如果运行 Bash 3.2
brew install bash-completion

# 或者，如果运行 Bash 4.1+
brew install bash-completion@2

请注意，在 .bashrc 中加载 Stern bash 完成代码之前，必须先加载 bash-completion。

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

如果通过 Krew 安装，请使用：

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

如果您使用 zsh，只需在 .zshrc 中加载 Stern zsh 完成代码即可。

source <(stern --completion=zsh)

如果您使用 fish shell，只需加载 Stern fish 完成代码即可。

stern --completion=fish | source

# 要为每个会话加载补全，执行一次：
stern --completion=fish >~/.config/fish/completions/stern.fish

使用容器运行

您也可以使用容器来运行stern：

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

如果您正在使用minikube集群，则需要按以下方式运行容器：

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

您可以在 https://github.com/orgs/stern/packages/container/package/stern 找到镜像标签。

在 Kubernetes Pod 中运行

如果你想在 Kubernetes Pod 中使用 stern，你需要创建以下 ClusterRole 并将其绑定到 ServiceAccount。

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