You are viewing documentation for Kubernetes version: v1.23
Kubernetes v1.23 documentation is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see the latest version.
系统日志
系统组件的日志记录集群中发生的事件,这对于调试非常有用。 你可以配置日志的精细度,以展示更多或更少的细节。 日志可以是粗粒度的,如只显示组件内的错误, 也可以是细粒度的,如显示事件的每一个跟踪步骤(比如 HTTP 访问日志、pod 状态更新、控制器动作或调度器决策)。
Klog
klog 是 Kubernetes 的日志库。 klog 为 Kubernetes 系统组件生成日志消息。
有关 klog 配置的更多信息,请参见命令行工具参考。
Kubernetes 正在进行简化其组件日志的努力。下面的 klog 命令行参数从 Kubernetes 1.23 开始已被废弃, 会在未来版本中移除:
--add-dir-header
--alsologtostderr
--log-backtrace-at
--log-dir
--log-file
--log-file-max-size
--logtostderr
--one-output
--skip-headers
--skip-log-headers
--stderrthreshold
输出总会被写到标准错误输出(stderr)之上,无论输出格式如何。 对输出的重定向将由调用 Kubernetes 组件的软件来处理。 这一软件可以是 POSIX Shell 或者类似 systemd 这样的工具。
在某些场合下,例如对于无发行主体的(distroless)容器或者 Windows 系统服务,
这些替代方案都是不存在的。那么你可以使用
kube-log-runner
可执行文件来作为 Kubernetes 的封装层,完成对输出的重定向。
在很多 Kubernetes 基础镜像中,都包含一个预先构建的可执行程序。
这个程序原来称作 /go-runner
,而在服务器和节点的发行版本库中,称作 kube-log-runner
。
下表展示的是 kube-log-runner
调用与 Shell 重定向之间的对应关系:
用法 | POSIX Shell(例如 Bash) | kube-log-runner <options> <cmd> |
---|---|---|
合并 stderr 与 stdout,写出到 stdout | 2>&1 |
kube-log-runner (默认行为 ) |
将 stderr 与 stdout 重定向到日志文件 | 1>>/tmp/log 2>&1 |
kube-log-runner -log-file=/tmp/log |
输出到 stdout 并复制到日志文件中 | 2>&1 | tee -a /tmp/log |
kube-log-runner -log-file=/tmp/log -also-stdout |
仅将 stdout 重定向到日志 | >/tmp/log |
kube-log-runner -log-file=/tmp/log -redirect-stderr=false |
klog 输出
传统的 klog 原生格式示例:
I1025 00:15:15.525108 1 httplog.go:79] GET /api/v1/namespaces/kube-system/pods/metrics-server-v0.3.1-57c75779f-9p8wg: (1.512ms) 200 [pod_nanny/v0.0.0 (linux/amd64) kubernetes/$Format 10.56.1.19:51756]
消息字符串可能包含换行符:
I1025 00:15:15.525108 1 example.go:79] This is a message
which has a line break.
结构化日志
Kubernetes v1.23 [beta]
迁移到结构化日志消息是一个正在进行的过程。在此版本中,并非所有日志消息都是结构化的。 解析日志文件时,你也必须要处理非结构化日志消息。
日志格式和值的序列化可能会发生变化。
结构化日志记录旨在日志消息中引入统一结构,以便以编程方式提取信息。 你可以方便地用更小的开销来处理结构化日志。 生成日志消息的代码决定其使用传统的非结构化的 klog 还是结构化的日志。
默认的结构化日志消息是以文本形式呈现的,其格式与传统的 klog 保持向后兼容:
<klog header> "<message>" <key1>="<value1>" <key2>="<value2>" ...
示例:
I1025 00:15:15.525108 1 controller_utils.go:116] "Pod status updated" pod="kube-system/kubedns" status="ready"
字符串在输出时会被添加引号。其他数值类型都使用 %+v
来格式化,因此可能导致日志消息会延续到下一行,
具体取决于数据本身。
I1025 00:15:15.525108 1 example.go:116] "Example" data="This is text with a line break\nand \"quotation marks\"." someInt=1 someFloat=0.1 someStruct={StringField: First line,
second line.}
JSON 日志格式
Kubernetes v1.19 [alpha]
JSON 输出并不支持太多标准 klog 参数。对于不受支持的 klog 参数的列表, 请参见命令行工具参考。
并不是所有日志都保证写成 JSON 格式(例如,在进程启动期间)。 如果你打算解析日志,请确保可以处理非 JSON 格式的日志行。
字段名和 JSON 序列化可能会发生变化。
--logging-format=json
参数将日志格式从 klog 原生格式改为 JSON 格式。
JSON 日志格式示例(美化输出):
{
"ts": 1580306777.04728,
"v": 4,
"msg": "Pod status updated",
"pod":{
"name": "nginx-1",
"namespace": "default"
},
"status": "ready"
}
具有特殊意义的 key:
ts
- Unix 时间风格的时间戳(必选项,浮点值)v
- 精细度(仅用于 info 级别,不能用于错误信息,整数)err
- 错误字符串(可选项,字符串)msg
- 消息(必选项,字符串)
当前支持JSON格式的组件列表:
日志清洗
Kubernetes v1.20 [alpha]
日志清洗(Log Sanitization)可能会导致大量的计算开销,因此不应在生产环境中启用。
--experimental-logging-sanitization
参数可用来启用 klog 清洗过滤器。
如果启用后,将检查所有日志参数中是否有标记为敏感数据的字段(比如:密码,密钥,令牌),
并且将阻止这些字段的记录。
当前支持日志清洗的组件列表:
- kube-controller-manager
- kube-apiserver
- kube-scheduler
- kubelet
日志清洗过滤器不会阻止用户工作负载日志泄漏敏感数据。
日志精细度级别
参数 -v
控制日志的精细度。增大该值会增大日志事件的数量。
减小该值可以减小日志事件的数量。增大精细度会记录更多的不太严重的事件。
精细度设置为 0 时只记录关键(critical)事件。
日志位置
有两种类型的系统组件:运行在容器中的组件和不运行在容器中的组件。例如:
- Kubernetes 调度器和 kube-proxy 在容器中运行。
- kubelet 和容器运行时不在容器中运行。
在使用 systemd 的系统中,kubelet 和容器运行时写入 journald。
在别的系统中,日志写入 /var/log
目录下的 .log
文件中。
容器中的系统组件总是绕过默认的日志记录机制,写入 /var/log
目录下的 .log
文件。
与容器日志类似,你应该轮转 /var/log
目录下系统组件日志。
在 kube-up.sh
脚本创建的 Kubernetes 集群中,日志轮转由 logrotate
工具配置。
logrotate
工具,每天或者当日志大于 100MB 时,轮转日志。
What's next
- 阅读 Kubernetes 日志架构
- 阅读结构化日志提案(英文)
- 阅读 klog 参数的废弃(英文)
- 阅读日志严重级别约定(英文)