kyverno/docs/dev/logging/logging.md

Logging Guideline

Logging in Kyverno follows a structured approach using logr, with zerologr for structured logging and klogr for Kubernetes client logs, ensuring consistency and standardization.

Log Levels

• Default log level: 2
• Can be modified via command-line argument: -v=<level_int>.
• Uses zerologr for structured logging (verbose logs) and klogr for client logs, both implemented through logr (Go's built-in logging interface).

⚠️ Initially, call depth applied to the logger does not get set. When logging.Setup is called in main, globalLog is switched to the real logger, meaning all loggers created after logging.Setup will work correctly if the underlying sink supports it.

Identifiers

• WithName: logging.WithName("setup") → Adds "setup" as a prefix.
• WithValues: logging.WithValues("key", "value") → Adds key-value pairs to logs.
• ControllerLogger: logging.ControllerLogger("name") → Creates a logger for controllers, setting a log level of 3.

Error Logging (L0)

logging.Error(err, "failed due to this error", "key", "value")
logging.Info("failed due to this error", err)

• Prints a stack trace where the error was defined for deeper debugging.
• Fatal logs do not exist; the caller must use os.Exit() explicitly.

Startup Info & Policy Application Results (L2)

logging.V(2).Info("starting controller", "workers", c.workers)
logging.V(2).Info("setup metrics", "otel", otel, "port", metricsPort)

• Logs providing information about startup processes or policy application results.

Variable Evaluation Logs (L3)

logging.V(3).Info("evaluating variable", "value", someVariable)
logging.V(3).Info("failed to fetch UR, falling back", "reason", err.Error())

• Logs related to dynamic evaluations, variable processing, or intermediate policy decisions.

Debugging Logs (L4 & Above)

logging.V(4).Info("fetching downstream resource", "APIVersion", generatePattern.GetAPIVersion())
logging.V(4).Info("ForceFailurePolicyIgnore is enabled, all policies with failures will be set to Ignore")

• Detailed logs useful for debugging execution paths.
• Shutdown messages should also be logged at L4.

---