Skip to content

Document resource attributes on NGINX Ingress Controller process logs #2275

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
promptless wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Document resource attributes on NGINX Ingress Controller process logs #2275

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
22 changes: 22 additions & 0 deletions content/nic/logging-and-monitoring/logging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,28 @@ The value `debug` is useful for troubleshooting: you will be able to see how NGI

Read more about NGINX Ingress Controller [command-line arguments]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md" >}}).

### Resource attributes on process log lines

In a multi-tenant cluster, these attributes let you filter, route, and triage the NGINX Ingress Controller process log lines by namespace or resource, and trace a log line back to the object that produced it, without manual investigation. To make this possible, NGINX Ingress Controller stamps its process log lines with the identity of the Kubernetes resource it is processing.

Three attributes carry this identity:

- `resource_namespace`: the resource's namespace.

@promptless promptless Bot Sep 10, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

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.

Source: https://github.com/nginx/kubernetes-ingress/blob/3d919410cf6982abb72db593ffb272dc9cfde5eb/internal/k8s/controller.go#L84-L86

- `resource_kind`: the resource's kind, such as `Ingress`, `VirtualServer`, `VirtualServerRoute`, `TransportServer`, or `Policy`.
- `resource_name`: the resource's name.

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.

@promptless promptless Bot Sep 10, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

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.

Source: https://github.com/nginx/kubernetes-ingress/blob/3d919410cf6982abb72db593ffb272dc9cfde5eb/internal/k8s/namespace.go#L20


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.

@promptless promptless Bot Sep 10, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

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.

Source: https://github.com/nginx/kubernetes-ingress/blob/3d919410cf6982abb72db593ffb272dc9cfde5eb/internal/logger/glog/handler.go#L109-L127

@promptless promptless Bot Sep 10, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

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.

Source: https://github.com/nginx/kubernetes-ingress/blob/3d919410cf6982abb72db593ffb272dc9cfde5eb/cmd/nginx-ingress/main.go#L1273-L1280

@promptless promptless Bot Sep 10, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

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:

documentation/content/nic/configuration/global-configuration/command-line-arguments.md

Lines 296 to 302 in 6a03820

<a name="cmdoption-log-format"></a>
### -log-format `<string>`
Log format for Ingress Controller logs. Allowed values: glog, json, text.
- Default is `glog`.


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

@promptless promptless Bot Sep 10, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

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.

Source: https://github.com/nginx/kubernetes-ingress/blob/3d919410cf6982abb72db593ffb272dc9cfde5eb/internal/k8s/controller.go#L3054-L3071

```

## NGINX Logs

NGINX includes two logs:
Expand Down
Loading