diff --git a/docs/Developer-Guide.md b/docs/Developer-Guide.md index a2c2bd2a11..eccadefa30 100644 --- a/docs/Developer-Guide.md +++ b/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). diff --git a/src/runtime-rs/crates/runtimes/src/manager.rs b/src/runtime-rs/crates/runtimes/src/manager.rs index d5b59cbce1..436a31d25a 100644 --- a/src/runtime-rs/crates/runtimes/src/manager.rs +++ b/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, @@ -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 });