Skip to content

Commit

Permalink
contextual logging: document promotion to beta
Browse files Browse the repository at this point in the history
  • Loading branch information
pohly committed Mar 6, 2024
1 parent fe2efe0 commit fcbeb85
Show file tree
Hide file tree
Showing 2 changed files with 16 additions and 11 deletions.
19 changes: 10 additions & 9 deletions content/en/docs/concepts/cluster-administration/system-logs.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ second line.}

### Contextual Logging

{{< feature-state for_k8s_version="v1.24" state="alpha" >}}
{{< feature-state for_k8s_version="v1.30" state="beta" >}}

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
Expand All @@ -133,8 +133,9 @@ 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
For Kubernetes {{< skew currentVersion >}}, this is gated behind the `ContextualLogging`
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) and is
enabled 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
Expand All @@ -147,14 +148,14 @@ $ 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)
ContextualLogging=true|false (BETA - default=true)
$ 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"
I0222 15:13:31.645988 197901 example.go:54] "runtime" logger="example.myname" foo="bar" duration="1m0s"
I0222 15:13:31.646007 197901 example.go:55] "another runtime" logger="example" foo="bar" duration="1h0m0s" duration="1m0s"
```

The `example` prefix and `foo="bar"` were added by the caller of the function
The `logger` key 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.

Expand All @@ -165,8 +166,8 @@ 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"
I0222 15:14:40.497333 198174 example.go:54] "runtime" duration="1m0s"
I0222 15:14:40.497346 198174 example.go:55] "another runtime" duration="1h0m0s" duration="1m0s"
```

### JSON log format
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@ stages:
- stage: alpha
defaultValue: false
fromVersion: "1.24"
- stage: beta
defaultValue: true
fromVersion: "1.30"
---
When you enable this feature gate, Kubernetes components that support
contextual logging add extra detail to log output.
When you disable this feature gate, Kubernetes components that support
contextual logging might produce less detailed log output because
some extra information might be provided only as part of the context.

0 comments on commit fcbeb85

Please sign in to comment.