debug: Improve logging, hide too chatty messages behind KCI_DEBUG

1)We add new env variable KCI_DEBUG to reduce amount of spam in logs.
Probably more work is pending in this direction.
2)Aadd flag -d to kci tool
3)Update documentation of kernelci-core about env variable,
and also basic documentation about other variables.
4)Create basic documentation for kci tool

Signed-off-by: Denys Fedoryshchenko <[email protected]>

Author: nuclearcat

doc/toml_settings.md

@@ -165,3 +165,41 @@ Then the `kci_build install_kernel` command normally requires `--kdir`,
 so they don't need to be provided on the command line: `db_config` is in the
 `[DEFAULT]` section, `db_token` in the `[db:localhost]` section and `kdir` in
 the `[kci_build]` section.
+
+## Environment Variables
+
+In addition to the TOML settings file, KernelCI tools support several
+environment variables for runtime configuration:
+
+| Variable | Description |
+|----------|-------------|
+| `KCI_API_TOKEN` | API authentication token |
+| `KCI_SETTINGS` | Path to the TOML settings file |
+| `KCI_INSTANCE` | Instance type (`prod`, `staging`) |
+| `KCI_INSTANCE_CALLBACK` | LAVA callback URL |
+| `KCI_STORAGE_CREDENTIALS` | Storage backend credentials |
+| `KCI_DEBUG` | Enable verbose debug logging |
+
+### `KCI_DEBUG`
+
+When `KCI_DEBUG` is set to `1`, `true`, or `yes`, KernelCI will output
+additional debug messages that are normally suppressed to reduce log noise.
+This includes verbose messages about job and platform filtering decisions
+during scheduling.
+
+Example usage:
+```bash
+export KCI_DEBUG=1
+# or
+KCI_DEBUG=true ./run-scheduler.sh
+```
+
+The `kci` CLI tool also provides a `--debug` / `-d` flag for commands that
+support it, which automatically sets `KCI_DEBUG=1`:
+
+```bash
+kci config forecast --debug -c /path/to/config
+```
+
+This is particularly useful for debugging why certain jobs or platforms are
+being filtered out during scheduling.

kernelci/api/helper.py

@@ -9,11 +9,23 @@
 
 from typing import Dict
 import json
+import os
 import requests
 
 from . import API
 
 
+def _is_debug_enabled():
+    """Check if KCI_DEBUG environment variable is set to enable verbose logging."""
+    return os.environ.get('KCI_DEBUG', '').lower() in ('1', 'true', 'yes')
+
+
+def _debug_print(message):
+    """Print message only if KCI_DEBUG is enabled."""
+    if _is_debug_enabled():
+        print(message)
+
+
 def merge(primary: dict, secondary: dict):
     """Deep merges dicts a and b, returning a new dict containing
     dictionary a updated with the contents of dictionary b.
@@ -480,13 +492,13 @@ def create_job_node(self, job_config, input_node,
             job_node['platform_filter'] = platform_filter
 
         if self._is_job_filtered(job_node):
-            print(f"Not creating node due to job filter. Job {job_config.name} "
-                  f"not found in jobfilter for node {input_node['id']}")
+            _debug_print(f"Not creating node due to job filter. Job {job_config.name} "
+                         f"not found in jobfilter for node {input_node['id']}")
             return None
 
         if not self.should_create_node(job_config.rules, job_node):
-            print(f"Not creating node due to job rules for {job_config.name} "
-                  f"evaluating node {input_node['id']}")
+            _debug_print(f"Not creating node due to job rules for {job_config.name} "
+                         f"evaluating node {input_node['id']}")
             return None
         # Test-specific fields inherited from parent node (kbuild or
         # job) if available
@@ -503,21 +515,21 @@ def create_job_node(self, job_config, input_node,
         if runtime:
             job_node['data']['runtime'] = runtime.config.name
             if not self.should_create_node(runtime.config.rules, job_node):
-                print(f"Not creating node {input_node['id']} due to runtime rules "
-                      f"for {runtime.config.name}")
+                _debug_print(f"Not creating node {input_node['id']} due to runtime rules "
+                             f"for {runtime.config.name}")
                 return None
         # Filter by platform if it is test job only
         if platform:
             # if platform_filter not null, verify if platform.name exist in platform_filter
             if platform_filter and platform.name not in platform_filter\
                and job_config.kind == 'job':
-                print(f"Filtered: Platform {platform.name} not found in platform_filter "
-                      f"for node {input_node['id']}")
+                _debug_print(f"Filtered: Platform {platform.name} not found in platform_filter "
+                             f"for node {input_node['id']}")
                 return None
             job_node['data']['platform'] = platform.name
             if not self.should_create_node(platform.rules, job_node):
-                print(f"Not creating node {input_node['id']} due to platform rules "
-                      f"for {platform.name}")
+                _debug_print(f"Not creating node {input_node['id']} due to platform rules "
+                             f"for {platform.name}")
                 return None
             # Process potential f-strings in node's data with platform attributes
             # krev is used for ChromeOS config version mapping

kernelci/cli/__init__.py

@@ -67,6 +67,10 @@ class Args:  # pylint: disable=too-few-public-methods
         '-v', '--verbose/--no-verbose', default=None,
         help="Print more details output"
     )
+    debug = click.option(
+        '-d', '--debug', is_flag=True, default=False,
+        help="Enable debug output (sets KCI_DEBUG=1)"
+    )
 
 
 def catch_error(func):

kernelci/cli/config.py

@@ -243,8 +243,11 @@ def do_forecast(merged_data):
 
 @kci_config.command
 @Args.config
-def forecast(config):
-    """Dump entries from the SECTION of the pipeline YAML configuration"""
+@Args.debug
+def forecast(config, debug):
+    """Forecast builds and tests for each tree/branch combination"""
+    if debug:
+        os.environ['KCI_DEBUG'] = '1'
     config_paths = kernelci.config.get_config_paths(config)
     if not config_paths:
         return