From 3d4720ace6de575c032d161d06318c94c29bb3e6 Mon Sep 17 00:00:00 2001 From: Anatolii Bazko Date: Tue, 30 Jun 2026 09:13:16 +0000 Subject: [PATCH] procedures: Update CLI Watcher documentation for auto-detection Update the CLI Watcher documentation to reflect the enhanced automatic process detection capability introduced in eclipse-che/che-machine-exec#363. Changes include: - Document new auto-detection mode with interactive/work process distinction - Add new configuration options (interactive, checkPeriod, activityWindow, gracePeriod, maxProcessAge) - Provide migration guidance for deprecated checkPeriodSeconds field - Update verification steps for both automatic and manual modes - Add examples for both automatic and manual configuration Co-Authored-By: Claude Sonnet 4.5 Signed-off-by: Anatolii Bazko --- ...pace-idling-for-long-running-commands.adoc | 98 ++++++++++++++++--- 1 file changed, 87 insertions(+), 11 deletions(-) diff --git a/modules/end-user-guide/pages/proc_preventing-workspace-idling-for-long-running-commands.adoc b/modules/end-user-guide/pages/proc_preventing-workspace-idling-for-long-running-commands.adoc index fde4f464a2..56c3857804 100644 --- a/modules/end-user-guide/pages/proc_preventing-workspace-idling-for-long-running-commands.adoc +++ b/modules/end-user-guide/pages/proc_preventing-workspace-idling-for-long-running-commands.adoc @@ -1,6 +1,6 @@ :_content-type: PROCEDURE -:description: Preventing {prod-short} workspace idling when long-running CLI tools are active in the terminal, so that unattended tasks can complete without interruption. -:keywords: user-guide, workspace, idling, idle, timeout, cli-watcher, noidle +:description: Preventing {prod-short} workspace idling when long-running CLI tools or interactive processes are active in the terminal, so that unattended tasks can complete without interruption. +:keywords: user-guide, workspace, idling, idle, timeout, cli-watcher, noidle, auto-detection, interactive-processes :navtitle: Prevent workspace idling for long-running commands :page-aliases: @@ -8,9 +8,9 @@ = Prevent workspace idling for long-running commands [role="_abstract"] -Prevent a workspace from stopping while long-running CLI tools such as `helm`, `odo`, or `sleep` are active, so that unattended tasks can complete without interruption. +Prevent a workspace from stopping while long-running CLI tools or interactive processes are active, so that unattended tasks can complete without interruption. -The CLI Watcher periodically checks for running processes that match the commands you specify. When it detects an active watched command, it resets the workspace idle timer. This configuration works entirely in user space and does not require administrator privileges. +The CLI Watcher periodically checks for running terminal processes and intelligently distinguishes between interactive processes (such as `vim` or REPLs) and work processes (such as `helm`, `odo`, or builds). It can automatically detect all processes or monitor specific commands you configure. When it detects activity, it resets the workspace idle timer. This configuration works entirely in user space and does not require administrator privileges. .Prerequisites @@ -18,7 +18,19 @@ The CLI Watcher periodically checks for running processes that match the command .Procedure -. Create a `.noidle` file in your workspace: +. Create a `.noidle` file in your workspace. You can use automatic detection or manual configuration: ++ +*Automatic detection (recommended):* ++ +[source,yaml] +---- +enabled: true +interactive: auto +---- ++ +The CLI Watcher automatically detects all terminal processes and distinguishes between interactive processes (such as `vim`, `python` REPLs) and work processes (such as builds, deployments). Interactive processes prevent idling only when actively used, while work processes always prevent idling. ++ +*Manual configuration:* + [source,yaml] ---- @@ -26,16 +38,34 @@ enabled: true watchedCommands: - helm - odo - - sleep -checkPeriodSeconds: 60 + - gradle +interactive: false +---- ++ +Manually specify which commands to monitor. Only listed processes prevent workspace idling. ++ +*Advanced configuration options:* ++ +[source,yaml] +---- +enabled: true +interactive: auto +checkPeriod: 1m +activityWindow: 2m +gracePeriod: 30s +maxProcessAge: 10m ---- + Where: + -- -`enabled`:: Enables or disables the CLI Watcher. Set to `true` to activate it. -`watchedCommands`:: A list of command names to monitor. When any of these commands are detected as a running process, the workspace idle timer is reset. -`checkPeriodSeconds`:: The polling interval in seconds. The default value is `60`. +`enabled`:: Enables or disables the CLI Watcher. Set to `true` to activate it. Default: `true`. +`interactive`:: Controls how processes are treated. Options: `auto` (automatic detection), `true`/`yes` (treat all processes as interactive), `false`/`no` (treat all as work processes). Default: `auto`. +`watchedCommands`:: Optional list of command names to monitor in manual mode. When `interactive: false` and this list is specified, only these commands prevent idling. +`checkPeriod`:: The polling interval. Accepts duration strings such as `30s`, `1m`, `90s`. Default: `1m`. +`activityWindow`:: Time window for detecting interactive process activity. Interactive processes must show activity within this window to prevent idling. Default: `2m`. +`gracePeriod`:: Additional time to wait after a work process completes before allowing idling. Default: `30s`. +`maxProcessAge`:: Maximum age for a process to be considered active. Processes older than this are ignored. Default: `10m`. -- . Place the `.noidle` file in one of the following locations, listed from highest to lowest priority: @@ -48,7 +78,15 @@ If the CLI Watcher finds no configuration file, it waits and checks again on the .Verification -. Start a watched command in the terminal (for example, `sleep 600`). +* In automatic detection mode (`interactive: auto`): +. Start an interactive process (for example, `vim file.txt` or `python`). +. Interact with the process (edit text, run commands). +. Verify that the workspace remains active while the process is in use. +. Leave the interactive process idle (no keyboard input) for longer than the `activityWindow`. +. Verify that the workspace can now idle. + +* In manual configuration mode: +. Start a watched command in the terminal (for example, `sleep 600` if `sleep` is in `watchedCommands`). . Verify that the workspace remains active beyond the configured idle timeout. [NOTE] @@ -57,3 +95,41 @@ The `.noidle` file supports live updates. You can add, edit, or remove the file The following processes are always excluded from watching and do not prevent workspace idling: PID 1 (the main container process) and `tail`. ==== + +[IMPORTANT] +==== +*Migration from previous versions:* + +If you are upgrading from a previous version of {prod-short} and have an existing `.noidle` configuration: + +* The `checkPeriodSeconds` field is deprecated. Replace it with `checkPeriod` using duration syntax: ++ +[source,yaml] +---- +# Old format +checkPeriodSeconds: 60 + +# New format +checkPeriod: 1m +---- + +* To maintain the previous behavior (manual process watching), explicitly set `interactive: false`: ++ +[source,yaml] +---- +enabled: true +interactive: false # Preserve manual watching mode +watchedCommands: + - helm + - odo + - sleep +---- + +* To enable the new automatic detection feature, set `interactive: auto` and remove the `watchedCommands` list: ++ +[source,yaml] +---- +enabled: true +interactive: auto # Enable automatic process detection +---- +====