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.