feat: Collect the containerdebug logs

CHANGELOG.md

@@ -10,6 +10,8 @@ All notable changes to this project will be documented in this file.
   ([#1021]).
 - Support Kerberos (GSSAPI) authentication on KRaft controllers, covering both
   broker-to-controller and controller-to-controller (Raft) traffic ([#1024]).
+- The logs of the `containerdebug` process are now collected by the Vector agent and forwarded to
+  the Vector aggregator ([#1055]).
 - Support for Kafka 4.3.1 ([#1022]).
 - Add `/ready` endpoint to the operator Deployment, which reports the CRD installation status ([#1029]).
 - Brokers now have a default affinity to the OPA Pods when OPA authorization is configured ([#1035]).
@@ -71,6 +73,10 @@ All notable changes to this project will be documented in this file.
 - `spec.clusterConfig.metadataManager` now uses PascalCase values (`ZooKeeper` and `KRaft`) as per
   Kubernetes conventions. The lowercase values `zookeeper` and `kraft` are deprecated, but are still
   accepted for backwards compatibility and may be removed in a future release ([#1034]).
+- The `containerdebug` process writes its log file again. The operator set
+  `CONTAINERDEBUG_LOG_DIRECTORY`, which containerdebug stopped reading in its version 0.2.0 when it
+  moved to `stackable-telemetry`; the directory is now set via `FILE_LOG_DIRECTORY`. The file is
+  rotated hourly and at most two files are kept, because rotation is opt-in ([#1055]).
 
 ### Removed
 
@@ -106,6 +112,7 @@ All notable changes to this project will be documented in this file.
 [#1049]: https://github.com/stackabletech/kafka-operator/pull/1049
 [#1051]: https://github.com/stackabletech/kafka-operator/pull/1051
 [#1052]: https://github.com/stackabletech/kafka-operator/pull/1052
+[#1055]: https://github.com/stackabletech/kafka-operator/pull/1055
 
 ## [26.7.0] - 2026-07-21
 

docs/modules/kafka/pages/usage-guide/logging.adoc

@@ -14,4 +14,12 @@ spec:
         enableVectorAgent: true
 ----
 
+NOTE: The logs of the xref:concepts:observability/containerdebug.adoc[`containerdebug` process] are collected as well.
+They are labelled `container: containerdebug`, although no such Kubernetes container exists.
+The process runs in the background of the `kafka` container.
+The label comes from `/stackable/log/containerdebug`, the directory which the operator sets with the `FILE_LOG_DIRECTORY` environment variable and from which the Vector agent derives the container name.
+Overriding `FILE_LOG_DIRECTORY` with `envOverrides` therefore changes how these logs are aggregated.
+The agent only collects files one level below `/stackable/log`, so a sibling directory such as `/stackable/log/kafka` relabels the events instead of dropping them, while any deeper or shallower path stops the aggregation.
+A path outside `/stackable/log` also leaves the size-capped log volume.
+
 Further information on how to configure logging, can be found in xref:concepts:logging.adoc[].

rust/operator-binary/src/controller/build/command.rs

@@ -60,6 +60,7 @@ pub fn broker_kafka_container_commands(
         {COMMON_BASH_TRAP_FUNCTIONS}
         {remove_vector_shutdown_file_command}
         prepare_signal_handlers
+        mkdir --parents \"$FILE_LOG_DIRECTORY\"
         containerdebug --output={STACKABLE_LOG_DIR}/containerdebug-state.json --loop &
         {set_realm_env}
 
@@ -154,6 +155,7 @@ pub fn controller_kafka_container_command(
         {COMMON_BASH_TRAP_FUNCTIONS}
         {remove_vector_shutdown_file_command}
         prepare_signal_handlers
+        mkdir --parents \"$FILE_LOG_DIRECTORY\"
         containerdebug --output={STACKABLE_LOG_DIR}/containerdebug-state.json --loop &
         {set_realm_env}
 

rust/operator-binary/src/controller/build/container.rs

@@ -5,6 +5,7 @@
 
 use std::str::FromStr;
 
+use const_format::concatcp;
 use stackable_operator::{
     builder::pod::{container::FieldPathEnvVar, volume::VolumeBuilder},
     commons::{
@@ -42,8 +43,13 @@ use crate::{
 stackable_operator::constant!(pub(crate) POD_NAME: EnvVarName = "POD_NAME");
 stackable_operator::constant!(KAFKA_CLIENT_PORT: EnvVarName = "KAFKA_CLIENT_PORT");
 stackable_operator::constant!(EXTRA_ARGS: EnvVarName = "EXTRA_ARGS");
-// Needed for the `containerdebug` process to log its tracing information to.
-stackable_operator::constant!(pub(crate) CONTAINERDEBUG_LOG_DIRECTORY: EnvVarName = "CONTAINERDEBUG_LOG_DIRECTORY");
+// Let the `containerdebug` process write its tracing information to a file. These are the generic
+// `stackable-telemetry` variables and apply to the whole Kafka container, so any other
+// telemetry-based process in it would log into the same directory and the Vector agent would label
+// its events with `container: containerdebug`.
+stackable_operator::constant!(pub(crate) FILE_LOG_DIRECTORY: EnvVarName = "FILE_LOG_DIRECTORY");
+stackable_operator::constant!(FILE_LOG_MAX_FILES: EnvVarName = "FILE_LOG_MAX_FILES");
+stackable_operator::constant!(FILE_LOG_ROTATION_PERIOD: EnvVarName = "FILE_LOG_ROTATION_PERIOD");
 
 // The env var and the ZooKeeper discovery ConfigMap key holding the ZooKeeper connection
 // string (the same string, as the env var name is used as the ConfigMap key).
@@ -103,10 +109,15 @@ pub(crate) fn common_kafka_env(
             &KAFKA_LOG4J_OPTS,
             kafka_log_opts(&resolved_product_image.product_version),
         )
+        // The directory must be exactly one level below the log directory, because the Vector
+        // agent derives the container name from that path segment.
         .with_value(
-            &CONTAINERDEBUG_LOG_DIRECTORY,
-            format!("{STACKABLE_LOG_DIR}/containerdebug"),
+            &FILE_LOG_DIRECTORY,
+            concatcp!(STACKABLE_LOG_DIR, "/containerdebug"),
         )
+        // Rotation is opt-in, so without these the file would grow unbounded.
+        .with_value(&FILE_LOG_ROTATION_PERIOD, "hourly")
+        .with_value(&FILE_LOG_MAX_FILES, "2")
         .with_value(
             &KAFKA_NODE_ID_OFFSET,
             node_id_hash32_offset(kafka_role, role_group_name.as_ref()).to_string(),
@@ -169,7 +180,9 @@ mod tests {
         let _ = *POD_NAME;
         let _ = *KAFKA_CLIENT_PORT;
         let _ = *EXTRA_ARGS;
-        let _ = *CONTAINERDEBUG_LOG_DIRECTORY;
+        let _ = *FILE_LOG_DIRECTORY;
+        let _ = *FILE_LOG_MAX_FILES;
+        let _ = *FILE_LOG_ROTATION_PERIOD;
         let _ = *ZOOKEEPER;
         let _ = *ZOOKEEPER_CONFIG_MAP_KEY;
     }

rust/operator-binary/src/controller/build/properties/product_logging/mod.rs

@@ -127,5 +127,7 @@ mod tests {
         // The two Kafka log formats must be handled ...
         assert!(content.contains("files_log4j"));
         assert!(content.contains("files_log4j2"));
+        assert!(content.contains("files_tracing_rs"));
+        assert!(content.contains("*.tracing-rs.json"));
     }
 }