Manual Chapter : Run Heuristic Health Checks

Updated Date: 11/03/2026

Run Heuristic Health Checks

Use the health engine to run diagnostic health checks directly on your F5OS platform. The engine loads and runs heuristic scripts that check for known conditions and provide recommendations.

  • You have access to the F5OS bash prompt or the confd CLI.
  • Your platform is running a supported version of F5OS.

The h-engine command lets you load, filter, and run heuristic scripts.

To run all available heuristic scripts on the platform:

h-engine run

To run a specific heuristic by its unique identifier:

h-engine run --id H00001

To load and run all heuristic scripts in a specific directory:

h-engine run --dir /path/to/heuristics/

A suite file groups one or more heuristics into a single file. To run a suite:

h-engine run --suite /path/to/suite-file

For more details on suite files, see Health Engine API and metadata reference.

To run only heuristics that match specific tags:

h-engine run --tags data-path,control-plane

To run only heuristics that apply to a specific platform role (such as blade, controller, appliance, or partition):

h-engine run --role blade

After heuristics run, you can view system health recommendations through the confd CLI:

show system health recommendations nodes node recommendation

The output shows the affected node, component, recommended action, a description of the issue, and the severity level.

show system health recommendations nodes node <node-name> recommendation <id> state action

The output shows the details of a specific recommendation, including the recommended action and other state information.

You can clear health recommendations at three levels: across the entire system, for a specific node, or for a single recommendation. Clearing a recommendation removes it from the active list after you’ve resolved the issue or completed maintenance.

Use the global clear command to remove all health recommendations across every node in the system. This is useful after system-wide maintenance or after you’ve resolved multiple issues at once.

Run the following command:

system health recommendations clear

Output fields

  • items: A list of the cleared recommendations. Each item includes the recommended action and a description of the issue.
  • count: The total number of recommendations cleared.

Example output

yaml
items:
  - action: reboot
    description: Blade requires reboot to complete firmware update
  - action: replace
    description: Drive has exceeded error threshold
count: 2

Use the node-level clear command to remove all health recommendations for a single node. This is useful after you’ve completed maintenance or resolved all issues on a particular node, such as a blade or controller.

Run the following command, replacing <node-name> with the name of the target node:

system health recommendations nodes node <node-name> clear

Example

To clear all recommendations for blade-1:

system health recommendations nodes node blade-1 clear

Output fields

  • items: A list of the cleared recommendations for that node. Each item includes the recommended action and a description of the issue.
  • count: The number of recommendations cleared for the specified node.

Example output

yaml
items:
  - action: investigate
    description: High CPU utilization detected
count: 1

Use the individual clear command to remove one specific health recommendation. This is useful after you’ve addressed a particular issue or when a recommendation no longer applies.

Run the following command, replacing <node-name> with the name of the target node and <id> with the recommendation identifier:

system health recommendations nodes node <node-name> recommendation <id> clear

Example

To clear the recommendation with the identifier heuristic-001 on the appliance node:

system health recommendations nodes node appliance recommendation heuristic-001 clear

Output fields

  • action: The recommended action that was cleared.
  • description: A description of the cleared recommendation.

The engine writes results after each run to the following locations:

  • Full run results: ${log-dir}/results.json
  • Per-script results: ${log-dir}/<heuristic-id>.<iteration>/result.json

The default log directory is /var/log/h-engine/run_<date/time>.

For the complete result file schema and examples, see Health Engine API and metadata reference.

To get a more detailed view of script and engine execution:

h-engine run --debug

To run heuristics without writing individual per-script result files:

h-engine run --skip-results