Skip to content

cla keeper - Rule monitoring and management

cla keeper opens an interactive REPL (Read-Eval-Print Loop) for monitoring rule execution in Clarive.

Overview

The rule keeper is a monitoring system that tracks rule execution, performance metrics, and provides insights into rule behavior. It helps administrators understand how rules are performing and identify potential issues.

Prerequisites

Before using cla keeper, you must enable rule monitoring by setting the following parameter in your config/clarive.yml file:

# rule tracing and management
rule_keeper: 1

After changing this configuration, restart the web server for the changes to take effect.

What Happens When Rules Run

When rule monitoring is enabled, the system will:

  • Track Rule Execution: Monitor when rules start, complete, or fail
  • Performance Metrics: Collect execution time, memory usage, and resource consumption
  • Dependency Analysis: Track rule dependencies and execution order
  • Error Monitoring: Capture and log rule execution errors and exceptions
  • Resource Usage: Monitor CPU, memory, and I/O patterns during rule execution

Why Monitor Rules

Rule monitoring provides several benefits:

  • Performance Optimization: Identify slow-running rules and bottlenecks
  • Debugging: Quickly locate and resolve rule execution issues
  • Capacity Planning: Understand resource requirements for rule execution
  • Compliance: Track rule execution for audit and compliance purposes
  • Maintenance: Proactive identification of problematic rules before they impact production

Usage

cla keeper starts an interactive REPL where you can run monitoring commands.

Common Options

-c <CONFIG|config_file> select the config / environment to connect to

-e <command> execute a single command and exit

Examples

Execute a single command and exit:

cla keeper -e 'ps' -c myconfig
cla keeper -e 'ps W' -c myconfig
cla keeper -e 'ps t=form' -c myconfig
cla keeper -e 'help' -c myconfig

Start interactive REPL:

cla keeper -c myconfig

REPL Commands

Once in the keeper REPL, you can use the following commands:

help

Display help information for all available commands.

ps [options]

List running rules with pagination support.

Options: - W - Wide mode (show start/end times) - R - Show only running rules - t=type1,type2 - Filter by rule types (comma-separated)

Examples:

ps          # Show all rules
ps W        # Wide mode
ps R        # Only running rules
ps t=rule   # Only rule type
ps t=rule,workflow  # Multiple types

top

Show running rules with auto-refresh. Interactive mode with keyboard controls: - q - Quit - w - Toggle wide mode - r - Toggle running-only mode - t - Set type filter

next [row_number]

Show next page of results or jump to specific row.

prev

Show previous page of results.

size [number]

Set or show the page size for results (default: 25).

refresh [seconds]

Set refresh rate for top command (default: 0.5).

trace

Show trace information for a specific sequence number.

dsl

Show the DSL code for a specific sequence number.

doc

Show the full document for a specific sequence number.

kill

Send signal to process. If no signal specified, uses WINCH (28).

stash

Show the stash contents for a specific sequence number.

code [context_lines]

Show DSL code around a specific line from stack trace (default: 5 context lines).

Important

To be able to see code and trace information the rule needs to be killed with a signal 28 (WINCH) or 15 (TERM). That works as a breakpoint in the rule, and will store the current context information into the rule keeper database collection.

pid

Show process information for a specific PID.

del [to_seq]

Delete rule keeper entries from sequence range.

cleanup [mode]

Clean up old entries from the rule keeper: - old - Delete all entries > 1h old - truncate - Delete all entries

roadkill

Delete orphaned running rule_keeper entries (process missing or not owned by current user).

log

Write all return output to a text file.

close

Close log file and stop writing output.

hist [number|search_string]

View and retrieve command history: - No arguments - Show all history - Number - Execute command from history - Search string - Filter history

date

Show current date and time.

clear

Clear the screen and reset cursor position.

start

Start the Clarive runtime environment.

bye, quit, exit

Exit the REPL (also Ctrl+D).

Control

The rule keeper is controlled entirely by the rule_keeper configuration parameter:

  • Set to 1 to enable rule monitoring
  • Set to 0 to disable rule monitoring

No additional start/stop commands are needed the monitoring is automatically active when enabled in the configuration.