Document resource attributes on NGINX Ingress Controller process logs - #2275
Document resource attributes on NGINX Ingress Controller process logs#2275promptless[bot] wants to merge 1 commit into
Conversation
Document the resource_namespace, resource_kind, and resource_name structured attributes that NGINX Ingress Controller now stamps on its process log lines, so readers can filter, route, and triage controller logs by namespace or resource in multi-tenant clusters. Adds a subsection to the process-logs section covering the three attributes, when each appears, and how the -log-format value renders them, with an example glog log line. Documents nginx/kubernetes-ingress#10373.
github-actions
Bot
added
documentation
![promptless[bot]](https://avatars.githubusercontent.com/in/979718?s=60&v=4){kind=small}
|
|
||
| Three attributes carry this identity: | ||
|
|
||
| - `resource_namespace`: the resource's namespace. |
There was a problem hiding this comment.
Confirms the three structured log attribute keys resource_namespace, resource_kind, resource_name, defined as logNamespaceKey/logKindKey/logNameKey constants in internal/k8s/controller.go, added by nginx/kubernetes-ingress PR #10373 (merged). Backs the attribute names and definitions listed in logging.md lines 38-40.
|
|
||
| These attributes appear only on NGINX Ingress Controller process log lines emitted at any log level while it processes a resource. They do not appear in the NGINX access or error logs. | ||
|
|
||
| One, two, or all three attributes can appear, depending on the code path. A line about a namespace-scoped operation may carry only `resource_namespace` and `resource_kind`, while a line about a specific object carries all three. |
There was a problem hiding this comment.
Confirms the two-attribute case: for Namespace-scoped operations, the scoped logger carries only resource_namespace and resource_kind (via lbc.Logger.With(logNamespaceKey, ns.Name, logKindKey, namespaceKind)), with no resource_name attribute. Backs the "one, two, or all three attributes" claim in logging.md line 44. Every occurrence of logKindKey in the PR diff is paired with logNamespaceKey, and this Namespace-kind path is the only one that omits logNameKey while including logKindKey.
|
|
||
| One, two, or all three attributes can appear, depending on the code path. A line about a namespace-scoped operation may carry only `resource_namespace` and `resource_kind`, while a line about a specific object carries all three. | ||
|
|
||
| How the attributes render depends on the [`-log-format`]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-log-format" >}}) command-line argument. The `glog` format renders them as space-separated `key=value` pairs, placed after the `file:line]` bracket and before the message. The `json` format emits them as native JSON fields, and the `text` format emits them as `key=value` fields. |
There was a problem hiding this comment.
Confirms the glog Handle() renders handler-level (WithAttrs) and record-level attrs as space-separated key=value pairs, appended after the "]" that closes the file:line bracket and before the message. Backs the glog rendering claim in logging.md line 46.
|
|
||
| One, two, or all three attributes can appear, depending on the code path. A line about a namespace-scoped operation may carry only `resource_namespace` and `resource_kind`, while a line about a specific object carries all three. | ||
|
|
||
| How the attributes render depends on the [`-log-format`]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-log-format" >}}) command-line argument. The `glog` format renders them as space-separated `key=value` pairs, placed after the `file:line]` bracket and before the message. The `json` format emits them as native JSON fields, and the `text` format emits them as `key=value` fields. |
There was a problem hiding this comment.
Confirms -log-format=json and -log-format=text select stdlib slog.NewJSONHandler and slog.NewTextHandler respectively, which render slog attributes as native JSON fields (json) or key=value fields (text). Backs the json/text rendering claim in logging.md line 46.
|
|
||
| One, two, or all three attributes can appear, depending on the code path. A line about a namespace-scoped operation may carry only `resource_namespace` and `resource_kind`, while a line about a specific object carries all three. | ||
|
|
||
| How the attributes render depends on the [`-log-format`]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-log-format" >}}) command-line argument. The `glog` format renders them as space-separated `key=value` pairs, placed after the `file:line]` bracket and before the message. The `json` format emits them as native JSON fields, and the `text` format emits them as `key=value` fields. |
There was a problem hiding this comment.
Confirms the -log-format command-line argument, its anchor #cmdoption-log-format, and its allowed values (glog, json, text; default glog), which the cross-link in logging.md line 46 points to.
Source:
| The following example shows an NGINX Ingress Controller log line in the default `glog` format. It is illustrative, not runnable: | ||
|
|
||
| ```text | ||
| W20260806 14:07:23.267011 1 controller.go:3057] resource_namespace=log-test-1 resource_kind=VirtualServer resource_name=webapp1 Error trying to get the secret log-test-1/tls-secret for VirtualServer webapp1: secret doesn't exist or of an unsupported type |
There was a problem hiding this comment.
Source of the verbatim example log line: createVirtualServerEx scopes the logger with resource_namespace/resource_kind/resource_name (VirtualServer) at line 3054, and the Warnf call at line 3071 ("Error trying to get the secret %v for VirtualServer %v: %v") produces the message text shown in the example. Matches the log line quoted verbatim in the PR #10373 description and reproduced in logging.md line 51.
✅ Deploy Preview will be available once build job completes!
|
Documents nginx/kubernetes-ingress#10373 (merged). NGINX Ingress Controller version that ships this is not confirmed; the change targets
main(deploys continuously). Retarget to a release branch if it should ship with a specific version.Open in Promptless
NGINX Ingress Controller now stamps its process log lines with structured attributes —
resource_namespace,resource_kind, andresource_name— that identify the Kubernetes resource being processed. In multi-tenant clusters this lets operators filter, route, and triage controller logs by namespace or resource and trace a log line back to the object that produced it.This adds a "Resource attributes on process log lines" subsection to the NGINX Ingress Controller logging reference (
content/nic/logging-and-monitoring/logging.md). It defines the three attributes, notes that one, two, or all three appear depending on the code path, explains how the-log-formatvalue (glog, json, text) renders them, and includes an example glog log line. The attributes apply only to the controller process logs, not the NGINX access or error logs.Trigger Events