From 9fd0199a20ee11a62326056042b4bbecbc6e7f4b Mon Sep 17 00:00:00 2001 From: Qiming Teng Date: Wed, 30 Mar 2022 15:55:20 +0800 Subject: [PATCH] [zh] Resync system-logs --- .../cluster-administration/system-logs.md | 192 +++++++++++++----- 1 file changed, 144 insertions(+), 48 deletions(-) diff --git a/content/zh/docs/concepts/cluster-administration/system-logs.md b/content/zh/docs/concepts/cluster-administration/system-logs.md index 4fb9ba7c89..8548c82310 100644 --- a/content/zh/docs/concepts/cluster-administration/system-logs.md +++ b/content/zh/docs/concepts/cluster-administration/system-logs.md @@ -33,8 +33,6 @@ klog is the Kubernetes logging library. [klog](https://github.com/kubernetes/klo generates log messages for the Kubernetes system components. For more information about klog configuration, see the [Command line tool reference](/docs/reference/command-line-tools-reference/). - -An example of the klog native format: --> klog 是 Kubernetes 的日志库。 [klog](https://github.com/kubernetes/klog) @@ -42,26 +40,111 @@ klog 是 Kubernetes 的日志库。 有关 klog 配置的更多信息，请参见[命令行工具参考](/zh/docs/reference/command-line-tools-reference/)。 -klog 原始格式的示例： + +Kubernetes 正在进行简化其组件日志的努力。下面的 klog 命令行参数从 Kubernetes 1.23 +开始[已被废弃](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/2845-deprecate-klog-specific-flags-in-k8s-components)， +会在未来版本中移除： + +- `--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`](https://github.com/kubernetes/kubernetes/blob/d2a8a81639fcff8d1221b900f66d28361a170654/staging/src/k8s.io/component-base/logs/kube-log-runner/README.md) +可执行文件来作为 Kubernetes 的封装层，完成对输出的重定向。 +在很多 Kubernetes 基础镜像中，都包含一个预先构建的可执行程序。 +这个程序原来称作 `/go-runner`，而在服务器和节点的发行版本库中，称作 `kube-log-runner`。 + + +下表展示的是 `kube-log-runner` 调用与 Shell 重定向之间的对应关系： + + +| 用法 | POSIX Shell（例如 Bash） | `kube-log-runner ` | +| --------------------------------|--------------------------|------------------------------------| +| 合并 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. +``` + ### 结构化日志 -{{< feature-state for_k8s_version="v1.19" state="alpha" >}} +{{< feature-state for_k8s_version="v1.23" state="beta" >}} +{{< warning >}} -{{< warning >}} -到结构化日志消息的迁移是一个持续的过程。 -在此版本中，并非所有日志消息都是结构化的。 +迁移到结构化日志消息是一个正在进行的过程。在此版本中，并非所有日志消息都是结构化的。 解析日志文件时，你也必须要处理非结构化日志消息。 日志格式和值的序列化可能会发生变化。 @@ -69,27 +152,45 @@ Log formatting and value serialization are subject to change. 结构化日志记录旨在日志消息中引入统一结构，以便以编程方式提取信息。 你可以方便地用更小的开销来处理结构化日志。 -新的消息格式向后兼容，并默认启用。 +生成日志消息的代码决定其使用传统的非结构化的 klog 还是结构化的日志。 -结构化日志的格式： + +默认的结构化日志消息是以文本形式呈现的，其格式与传统的 klog 保持向后兼容： ```ini "" ="" ="" ... ``` - + 示例： ```ini I1025 00:15:15.525108 1 controller_utils.go:116] "Pod status updated" pod="kube-system/kubedns" status="ready" ``` + +字符串在输出时会被添加引号。其他数值类型都使用 [`%+v`](https://pkg.go.dev/fmt#hdr-Printing) +来格式化，因此可能导致日志消息会延续到下一行， +[具体取决于数据本身](https://github.com/kubernetes/kubernetes/issues/106428)。 + +``` +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 输出并不支持太多标准 klog 参数。 -对于不受支持的 klog 参数的列表，请参见 -[命令行工具参考](/zh/docs/reference/command-line-tools-reference/)。 +JSON 输出并不支持太多标准 klog 参数。对于不受支持的 klog 参数的列表， +请参见[命令行工具参考](/zh/docs/reference/command-line-tools-reference/)。 并不是所有日志都保证写成 JSON 格式（例如，在进程启动期间）。 如果你打算解析日志，请确保可以处理非 JSON 格式的日志行。 @@ -137,8 +237,9 @@ JSON 日志格式示例（美化输出）： 具有特殊意义的 key： * `ts` - Unix 时间风格的时间戳（必选项，浮点值） -* `v` - 精细度（必选项，整数，默认值 0） +* `v` - 精细度（仅用于 info 级别，不能用于错误信息，整数） * `err` - 错误字符串（可选项，字符串） * `msg` - 消息（必选项，字符串） 当前支持JSON格式的组件列表： + * {{< glossary_tooltip term_id="kube-controller-manager" text="kube-controller-manager" >}} * {{< glossary_tooltip term_id="kube-apiserver" text="kube-apiserver" >}} * {{< glossary_tooltip term_id="kube-scheduler" text="kube-scheduler" >}} @@ -158,43 +260,30 @@ List of components currently supporting JSON format: - -### 日志清理 +### 日志清洗 {#log-sanitization} {{< feature-state for_k8s_version="v1.20" state="alpha" >}} {{}} -日志清理可能会导致大量的计算开销，因此不应启用在生产环境中。 + +日志清洗（Log Sanitization）可能会导致大量的计算开销，因此不应在生产环境中启用。 {{< /warning >}} - -`--experimental-logging-sanitization` 参数可用来启用 klog 清理过滤器。 -如果启用后，将检查所有日志参数中是否有标记为敏感数据的字段（比如：密码，密钥，令牌），并且将阻止这些字段的记录。 +`--experimental-logging-sanitization` 参数可用来启用 klog 清洗过滤器。 +如果启用后，将检查所有日志参数中是否有标记为敏感数据的字段（比如：密码，密钥，令牌）， +并且将阻止这些字段的记录。 - -当前支持日志清理的组件列表： +当前支持日志清洗的组件列表： * kube-controller-manager * kube-apiserver @@ -202,7 +291,10 @@ The Log sanitization filter does not prevent user workload logs from leaking sen * kubelet {{< note >}} -日志清理过滤器不会阻止用户工作负载日志泄漏敏感数据。 + +日志清洗过滤器不会阻止用户工作负载日志泄漏敏感数据。 {{< /note >}} ### 日志位置 有两种类型的系统组件：运行在容器中的组件和不运行在容器中的组件。例如： + * Kubernetes 调度器和 kube-proxy 在容器中运行。 -* kubelet 和容器运行时，例如 Docker，不在容器中运行。 +* kubelet 和{{}}不在容器中运行。 * 阅读 [Kubernetes 日志架构](/zh/docs/concepts/cluster-administration/logging/) -* 阅读 [Structured Logging](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/1602-structured-logging) -* 阅读 [Conventions for logging severity](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/logging.md) +* 阅读[结构化日志提案（英文）](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/1602-structured-logging) +* 阅读 [klog 参数的废弃（英文）](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/2845-deprecate-klog-specific-flags-in-k8s-components) +* 阅读[日志严重级别约定（英文）](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/logging.md) +