Merge pull request #13147 from manuelh-dev/mahuber/debug-go-rust

runtime-rs: Honor enable_debug for logs and adjust debugging documentation

docs/Developer-Guide.md

@@ -126,16 +126,51 @@ Enable full debug as follows:
 
 ```bash
 $ sudo sed -i -E 's/^(\s*enable_debug\s*=\s*)false/\1true/' /etc/kata-containers/configuration.toml
-$ sudo sed -i -e 's/^kernel_params = "\(.*\)"/kernel_params = "\1 agent.log=debug initcall_debug"/g' /etc/kata-containers/configuration.toml
+$ sudo sed -i -e 's/^kernel_params = "\(.*\)"/kernel_params = "\1 initcall_debug"/g' /etc/kata-containers/configuration.toml
+```
+
+For both the Go runtime and runtime-rs, setting `enable_debug = true` in the
+relevant Kata configuration sections is the baseline for enabling debug
+behavior. Setting `enable_debug = true` in the `[agent.kata]` section adds the
+agent debug kernel parameter automatically, so `agent.log=debug` does not need
+to be added to `kernel_params` manually.
+
+The runtime-rs shim also supports component-level log filtering through
+`log_level`. For runtime-rs, `enable_debug = true` in the `[runtime]`,
+`[agent.kata]`, and selected `[hypervisor.*]` sections promotes the component
+log filter from the default `info` level to `debug`. If `log_level` is
+explicitly set to another level, such as `trace` or `warn`, the explicit value
+is honored.
+
+For example, with runtime-rs:
+
+```toml
+[runtime]
+log_level = "debug" # show runtime-rs shim messages in the kata journal
+
+[hypervisor.qemu]
+enable_debug = true # modify kernel parameters and QEMU invocation
+log_level = "debug" # show hypervisor component messages in the kata journal
+
+[agent.kata]
+enable_debug = true # add guest agent debug to kernel parameters
+log_level = "debug" # show forwarded agent messages in the kata journal
 ```
 
 ### debug logs and shimv2
 
-If you are using `containerd` and the Kata `containerd-shimv2` to launch Kata Containers, and wish
-to enable Kata debug logging, there are two ways this can be enabled via the `containerd` configuration file,
-detailed below.
+If you are using `containerd` and the Kata `containerd-shimv2` to launch Kata
+Containers, `containerd` debug logging can also be useful when debugging
+containerd, CRI, or shim launch behavior.
 
-The Kata logs appear in the `containerd` log files, along with logs from `containerd` itself.
+For the Go runtime, Kata logs appear in the `containerd` log files, along with
+logs from `containerd` itself, so `containerd` debug settings are commonly used
+for Kata debug output.
+
+For runtime-rs, the shim writes Kata logs to `journald` directly using the
+`kata` identifier. Enabling `containerd` debug is not required to see runtime-rs
+Kata debug logs; the runtime-rs `enable_debug` and `log_level` settings above
+are enough for those component logs.
 
 For more information about `containerd` debug, please see the
 [`containerd` documentation](https://github.com/containerd/containerd/blob/main/docs/getting-started.md).

src/runtime-rs/crates/runtimes/src/manager.rs

@@ -81,6 +81,28 @@ fn convert_string_to_slog_level(string_level: &str) -> slog::Level {
     }
 }
 
+fn effective_log_level(enable_debug: bool, log_level: &str) -> &str {
+    if enable_debug && log_level == "info" {
+        "debug"
+    } else {
+        log_level
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::effective_log_level;
+
+    #[test]
+    fn test_effective_log_level() {
+        assert_eq!(effective_log_level(false, "info"), "info");
+        assert_eq!(effective_log_level(false, "debug"), "debug");
+        assert_eq!(effective_log_level(true, "info"), "debug");
+        assert_eq!(effective_log_level(true, "trace"), "trace");
+        assert_eq!(effective_log_level(true, "warn"), "warn");
+    }
+}
+
 struct RuntimeHandlerManagerInner {
     id: String,
     msg_sender: Sender<Message>,
@@ -867,19 +889,22 @@ fn update_agent_kernel_params(config: &mut TomlConfig) -> Result<()> {
 // according to the settings read from configuration file
 fn update_component_log_level(config: &TomlConfig) {
     // Retrieve the log-levels set in configuration file, modify the FILTER_RULE accordingly
-    let default_level = String::from("info");
+    let default_level = "info";
     let agent_level = if let Some(agent_config) = config.agent.get(&config.runtime.agent_name) {
-        agent_config.log_level.clone()
+        effective_log_level(agent_config.debug, &agent_config.log_level)
     } else {
-        default_level.clone()
+        default_level
     };
     let hypervisor_level =
         if let Some(hypervisor_config) = config.hypervisor.get(&config.runtime.hypervisor_name) {
-            hypervisor_config.debug_info.log_level.clone()
+            effective_log_level(
+                hypervisor_config.debug_info.enable_debug,
+                &hypervisor_config.debug_info.log_level,
+            )
         } else {
-            default_level.clone()
+            default_level
         };
-    let runtime_level = config.runtime.log_level.clone();
+    let runtime_level = effective_log_level(config.runtime.debug, &config.runtime.log_level);
 
     // Update FILTER_RULE to apply changes
     FILTER_RULE.rcu(|inner| {
@@ -887,15 +912,15 @@ fn update_component_log_level(config: &TomlConfig) {
         updated_inner.clone_from(inner);
         updated_inner.insert(
             "runtimes".to_string(),
-            convert_string_to_slog_level(&runtime_level),
+            convert_string_to_slog_level(runtime_level),
         );
         updated_inner.insert(
             "agent".to_string(),
-            convert_string_to_slog_level(&agent_level),
+            convert_string_to_slog_level(agent_level),
         );
         updated_inner.insert(
             "hypervisor".to_string(),
-            convert_string_to_slog_level(&hypervisor_level),
+            convert_string_to_slog_level(hypervisor_level),
         );
         updated_inner
     });