Merge pull request #97347 from openshift-cherrypick-robot/cherry-pick-96619-to-rhacs-docs-4.7

[rhacs-docs-4.7] Update Collector troubleshooting guide

Author: kcarmichael08

modules/failing-to-load-the-ebpf-probe.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+//
+// * troubleshooting/commonly-occurring-error-conditions.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="failing-to-load-the-ebpf-probe_{context}"]
+= Failing to load the eBPF probe
+
+Before Collector starts, it loads the eBPF probe; however, in rare cases, you might encounter issues where Collector cannot load the eBPF probe, which results in various error messages or exceptions. In such cases, you must check the logs to identify the problems with failure in loading the eBPF probe.
+
+Consider the following Collector log:
+
+[source,terminal]
+----
+[...]
+[INFO    2025/07/24 10:26:37] Trying to open the right engine!
+[INFO    2025/07/24 10:26:41] libbpf: prog 'execve_x': -- BEGIN PROG LOAD LOG --
+[...]
+-- END PROG LOAD LOG --
+[INFO    2025/07/24 10:26:41] libbpf: prog 'execve_x': failed to load: -7
+[INFO    2025/07/24 10:26:41] libbpf: failed to load object 'bpf_probe'
+[INFO    2025/07/24 10:26:41] libbpf: failed to load BPF skeleton 'bpf_probe': -7
+[INFO    2025/07/24 10:26:41] libpman: failed to load BPF object (errno: 7 | message: Argument list too long)
+----
+
+If you encounter this kind of error, you must report it to {product-title} ({product-title-short}) support team or create an issue in the `stackrox/collector` GitHub repository.

modules/failing-to-load-the-kernel-driver.adoc

@@ -12,8 +12,6 @@ When starting, first check if you can connect to Sensor. Sensor is responsible f
 Collector Version: 3.15.0
 OS: Ubuntu 20.04.4 LTS
 Kernel Version: 5.4.0-126-generic
-Starting StackRox Collector...
-[INFO    2023/05/13 12:20:43] Hostname: 'hostname'
 [...]
 [INFO    2023/05/13 12:20:43] Sensor configured at address: sensor.stackrox.svc:9998
 [INFO    2023/05/13 12:20:43] Attempting to connect to Sensor
@@ -23,7 +21,7 @@ Starting StackRox Collector...
 [INFO    2023/05/13 12:21:13]  Kernel driver candidates:
 [INFO    2023/05/13 12:21:13] ====================================
 [INFO    2023/05/13 12:21:13]
-[FATAL   2023/05/13 12:21:13] Unable to connect to Sensor.
+[FATAL   2023/05/13 12:21:13] Unable to connect to Sensor at 'sensor.stackrox.svc:9998'.
 ----
 
 This error could mean that Sensor has not started correctly or that Collector configuration is incorrect. To fix this issue, you must verify Collector configuration to ensure that Sensor address is correct and that the Sensor pod is running correctly.

modules/unable-to-connect-to-the-sensor.adoc

@@ -8,34 +8,36 @@ toc::[]
 
 
 [role="_abstract"]
-Most errors occur during Collector startup when Collector configures itself and finds or downloads a kernel driver for the system.
+Most errors occur during Collector startup when Collector configures itself and loads eBPF probe into the system.
 
-The following diagram describes the main parts
-of Collector startup process:
+Collector startup process involves the following stages:
 
-.Collector pod startup process
-image::acs-collector-startup-process.png[Collector pod startup process]
+* Parse Configuration
+* Analyze Host
+* Connecting to Sensor
+* Loading eBPF probe
 
-If any part of the startup procedure fails, the logs display a diagnostic summary detailing which steps succeeded or failed . 
+Failure at any step is considered fatal. If any part of the startup
+procedure fails, the logs display a diagnostic summary with details about which steps
+succeeded or failed.
 
-The following log file example shows a successful startup:  
+The following log file example shows a successful startup:
 
 [source,terminal]
 ----
-[INFO    2022/11/28 13:21:55] == Collector Startup Diagnostics: ==
-[INFO    2022/11/28 13:21:55]  Connected to Sensor?       true
-[INFO    2022/11/28 13:21:55]  Kernel driver available?   true
-[INFO    2022/11/28 13:21:55]  Driver loaded into kernel? true
-[INFO    2022/11/28 13:21:55] ====================================
+[INFO    2025/07/24 10:05:54] == Collector Startup Diagnostics: ==
+[INFO    2025/07/24 10:05:54]  Connected to Sensor?       false
+[INFO    2025/07/24 10:05:54]  Kernel driver candidates:
+[INFO    2025/07/24 10:05:54]    core_bpf (available)
+[INFO    2025/07/24 10:05:54]  Driver loaded into kernel: core_bpf
+[INFO    2025/07/24 10:05:54] ====================================
 ----
 
-The log output confirms that Collector connected to Sensor and located and loaded the kernel driver. 
+The log output confirms that Collector connected to Sensor and loaded the eBPF probe.
 You can use this log to check for the successful startup of Collector.
 
 
 include::modules/unable-to-connect-to-the-sensor.adoc[leveloffset=+1]
 
-include::modules/unavailability-of-the-kernel-driver.adoc[leveloffset=+1]
-
-include::modules/failing-to-load-the-kernel-driver.adoc[leveloffset=+1]
+include::modules/failing-to-load-the-ebpf-probe.adoc[leveloffset=+1]