Merge pull request #32452 from pohly/contextual-logging

features: add ContextualLogging

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)

content/en/docs/reference/command-line-tools-reference/feature-gates.md

@@ -87,6 +87,7 @@ different Kubernetes components.
 | `CSIMigrationPortworx` | `false` | Alpha | 1.23 | |
 | `csiMigrationRBD` | `false` | Alpha | 1.23 | |
 | `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 | |
@@ -772,6 +773,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