From 4a57c111f9deb8b5ff40a8d1b98c53801becc5c9 Mon Sep 17 00:00:00 2001 From: Patrick Ohly Date: Wed, 23 Mar 2022 17:45:11 +0100 Subject: [PATCH] features: add ContextualLogging This is a new feature in 1.24. Only the infrastructure is going in at this point with no changes in Kubernetes components, so the user-visible effect is minimal. --- .../cluster-administration/system-logs.md | 50 +++++++++++++++++++ .../feature-gates.md | 3 ++ 2 files changed, 53 insertions(+) diff --git a/content/en/docs/concepts/cluster-administration/system-logs.md b/content/en/docs/concepts/cluster-administration/system-logs.md index 9d0359ddad..7e4619d67c 100644 --- a/content/en/docs/concepts/cluster-administration/system-logs.md +++ b/content/en/docs/concepts/cluster-administration/system-logs.md @@ -110,6 +110,55 @@ I1025 00:15:15.525108 1 example.go:116] "Example" data="This is text with second line.} ``` +### Contextual Logging + +{{< feature-state for_k8s_version="v1.24" state="alpha" >}} + +Contextual logging builds on top of structured logging. It is primarily about +how developers use logging calls: code based on that concept is more flexible +and supports additional use cases as described in the [Contextual Logging +KEP](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/3077-contextual-logging). + +If developers use additional functions like `WithValues` or `WithName` in +their components, then log entries contain additional information that gets +passed into functions by their caller. + +Currently this is gated behind the `StructuredLogging` feature gate and +disabled by default. The infrastructure for this was added in 1.24 without +modifying components. The +[`component-base/logs/example`](https://github.com/kubernetes/kubernetes/blob/v1.24.0-beta.0/staging/src/k8s.io/component-base/logs/example/cmd/logger.go) +command demonstrates how to use the new logging calls and how a component +behaves that supports contextual logging. + +```console +$ cd $GOPATH/src/k8s.io/kubernetes/staging/src/k8s.io/component-base/logs/example/cmd/ +$ go run . --help +... + --feature-gates mapStringBool A set of key=value pairs that describe feature gates for alpha/experimental features. Options are: + AllAlpha=true|false (ALPHA - default=false) + AllBeta=true|false (BETA - default=false) + ContextualLogging=true|false (ALPHA - default=false) +$ go run . --feature-gates ContextualLogging=true +... +I0404 18:00:02.916429 451895 logger.go:94] "example/myname: runtime" foo="bar" duration="1m0s" +I0404 18:00:02.916447 451895 logger.go:95] "example: another runtime" foo="bar" duration="1m0s" +``` + +The `example` prefix and `foo="bar"` were added by the caller of the function +which logs the `runtime` message and `duration="1m0s"` value, without having to +modify that function. + +With contextual logging disable, `WithValues` and `WithName` do nothing and log +calls go through the global klog logger. Therefore this additional information +is not in the log output anymore: + +```console +$ go run . --feature-gates ContextualLogging=false +... +I0404 18:03:31.171945 452150 logger.go:94] "runtime" duration="1m0s" +I0404 18:03:31.171962 452150 logger.go:95] "another runtime" duration="1m0s" +``` + ### JSON log format {{< feature-state for_k8s_version="v1.19" state="alpha" >}} @@ -197,5 +246,6 @@ The `logrotate` tool rotates logs daily, or once the log size is greater than 10 * Read about the [Kubernetes Logging Architecture](/docs/concepts/cluster-administration/logging/) * Read about [Structured Logging](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/1602-structured-logging) +* Read about [Contextual Logging](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/3077-contextual-logging) * Read about [deprecation of klog flags](https://github.com/kubernetes/enhancements/tree/master/keps/sig-instrumentation/2845-deprecate-klog-specific-flags-in-k8s-components) * Read about the [Conventions for logging severity](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-instrumentation/logging.md) diff --git a/content/en/docs/reference/command-line-tools-reference/feature-gates.md b/content/en/docs/reference/command-line-tools-reference/feature-gates.md index c6913341e6..2ed49eec18 100644 --- a/content/en/docs/reference/command-line-tools-reference/feature-gates.md +++ b/content/en/docs/reference/command-line-tools-reference/feature-gates.md @@ -93,6 +93,7 @@ different Kubernetes components. | `CSIStorageCapacity` | `false` | Alpha | 1.19 | 1.20 | | `CSIStorageCapacity` | `true` | Beta | 1.21 | | | `CSIVolumeHealth` | `false` | Alpha | 1.21 | | +| `ContextualLogging` | `false` | Alpha | 1.24 | | | `ControllerManagerLeaderMigration` | `false` | Alpha | 1.21 | 1.21 | | `ControllerManagerLeaderMigration` | `true` | Beta | 1.22 | | | `CustomCPUCFSQuotaPeriod` | `false` | Alpha | 1.12 | | @@ -737,6 +738,8 @@ Each feature gate is designed for enabling/disabling a specific feature: for fsGroups when mounting a volume in a Pod. See [Configure volume permission and ownership change policy for Pods](/docs/tasks/configure-pod-container/security-context/#configure-volume-permission-and-ownership-change-policy-for-pods) for more details. +- `ContextualLogging`: When you enable this feature gate, Kubernetes components that support + contextual logging add extra detail to log output. - `ControllerManagerLeaderMigration`: Enables leader migration for `kube-controller-manager` and `cloud-controller-manager`. - `CronJobControllerV2`: Use an alternative implementation of the