Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 34 additions & 15 deletions content/en/docs/concepts/cluster-administration/system-logs.md
Original file line number Diff line number Diff line change
Expand Up @@ -241,13 +241,32 @@ The `logrotate` tool rotates logs daily, or once the log size is greater than 10

{{< feature-state feature_gate_name="NodeLogQuery" >}}

To help with debugging issues on nodes, Kubernetes v1.27 introduced a feature that allows viewing logs of services
running on the node. To use the feature, ensure that the `NodeLogQuery`
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is enabled for that node, and that the
kubelet configuration options `enableSystemLogHandler` and `enableSystemLogQuery` are both set to true. On Linux
the assumption is that service logs are available via journald. On Windows the assumption is that service logs are
available in the application log provider. On both operating systems, logs are also available by reading files within
`/var/log/`.
The Log Query feature can help debugging issues in both Linux and Windows
nodes. Introduced in Kubernetes v1.27, the feature allows viewing logs of
services running on the node. To use the feature, ensure that the kubelet
configuration options `enableSystemLogHandler` and `enableSystemLogQuery`
are both set to _true_ for the target node.

In Kubernetes v1.36 this feature graduated to stable and the `NodeLogQuery`[feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
is now locked to _true_, hence the feature gate is enabled by default, leaving
`enableSystemLogHandler` as the only option required to enable or disable the
Log Query feature.

`enableSystemLogHandler` defaults to _false_ and is recommended to be left
disabled unless actively debugging.

{{< warning >}}
Granting permissions to `nodes/proxy` (even just **get** permission) also
authorizes access to powerful kubelet APIs that can be used to execute commands
in any container running on the node, so be careful about how you manage them.
See [Kubelet authentication/authorization](/docs/reference/access-authn-authz/kubelet-authn-authz/#get-nodes-proxy-warning)
for more information.
{{< /warning >}}

On Linux, the assumption is that service logs are available via _journald_. On
Windows the assumption is that service logs are available in the application log
provider. On both operating systems, logs are also available by reading files
within `/var/log/`.

Provided you are authorized to interact with node objects, you can try out this feature on all your nodes or
just a subset. Here is an example to retrieve the kubelet service logs from a node:
Expand All @@ -271,14 +290,14 @@ first checks the native logger and if that is not available attempts to retrieve

The complete list of options that can be used are:

Option | Description
------ | -----------
`boot` | boot show messages from a specific system boot
`pattern` | pattern filters log entries by the provided PERL-compatible regular expression
`query` | query specifies services(s) or files from which to return logs (required)
`sinceTime` | an [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) timestamp from which to show logs (inclusive)
`untilTime` | an [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) timestamp until which to show logs (inclusive)
`tailLines` | specify how many lines from the end of the log to retrieve; the default is to fetch the whole log
| Option | Description |
|-------------|-----------------------------------------------------------------------------------------------------|
| `boot` | boot show messages from a specific system boot |
| `pattern` | pattern filters log entries by the provided PERL-compatible regular expression |
| `query` | query specifies services(s) or files from which to return logs (required) |
| `sinceTime` | an [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) timestamp from which to show logs (inclusive) |
| `untilTime` | an [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) timestamp until which to show logs (inclusive) |
| `tailLines` | specify how many lines from the end of the log to retrieve; the default is to fetch the whole log |

Example of a more complex query:

Expand Down
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jrvaldes Also, please check the below linked page. We may want to adjust the wording around the NodeLogQuery feature‑gate enablement, since it’s graduating to GA and will be enabled by default and cannot be disabled by users.

https://kubernetes.io/docs/concepts/cluster-administration/system-logs/#log-query

Copy link
Copy Markdown
Author

@jrvaldes jrvaldes Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

right, updated in 4da7d9a

Original file line number Diff line number Diff line change
Expand Up @@ -13,5 +13,9 @@ stages:
- stage: beta
defaultValue: false
fromVersion: "1.30"
toVersion: "1.35"
- stage: stable
defaultValue: true
fromVersion: "1.36"
---
Enables querying logs of node services using the `/logs` endpoint.