Adding Rules

Add Rule Command Syntax

The rule add command adds a rule. Here is the syntax for the rule add command:

rule add [transient] <name> <action-name>(<action-args>) when <expression> [including <metric_list>]

transient
Rules may be persistent or transient. A persistent rule remains active until it is deleted, while a transient rule disappears when the rulesengine service is shut down on all hosts. Rules are persistent by default; you must include the transient keyword to create a transient rule.

<name>
A unique name for the rule. The name all is reserved.

<action-name>
The action to perform. One of the following:

  • host:throttle_gpdb_query – specify a maximum allowed CPU utilization percentage for a Greenplum Database query.
  • host:pg_cancel_backend - cancel the current query on a host by calling the PostgreSQL host:pg_cancel_backend() function.
  • pg_terminate_backend – terminate a session by calling the PostgreSQL pg_terminate_backend() function.
  • gpdb_record – record an event about a query in the gp_wlm_records table.

<action-args>
Arguments that pass values to the action, if needed. An argument is specified as an arg-name=value pair. Multiple arguments are separated by commas.

when <expression>
A Boolean expression that filters targets for the action. The expression references one or more metrics to filter the facts that trigger the action. The expression may contain Posix regular expressions (regex).

including <metric-list>
An optional, comma-separated list of metrics to add to the context when the rule triggers. Without an including clause, the action context contains only values for metrics referenced in the expression clause. Add the including clause to add values for additional metrics to the action context.

Metrics in the <metric_list> are specified without scope prefixes. If the Workload Manager rule compiler cannot find a metric in any currently bound scope, adding the rule fails with an error message.

When gpdb_record,host:pg_cancel_backend, and pg_terminate_backend actions are triggered, the metrics in <metric-list> are added to the context arguments columns in the gp_wlm_records table or gp_wlm_events view.

A metric in the including clause is not added to the context arguments columns if it is already present as a separate column. For example, the usename metric has its own column, so adding this metric to the including clause has no effect.

When the following rule action is triggered by a query that runs longer than 10 minutes, the values of total_cpu and spillfile_size_across_cluster metrics are recorded and shown in the context:

  mdw/gpdb-cluster> rule add myrule gpdb_record(message="rich context") 
  when session_id:host:pid:runtime > 600 
  including total_cpu, spillfile_size_across_cluster

Rule Actions

host:throttle_gpdb_query

Throttle a Greenplum Database query on a specified host.

Arguments:

  • max_cpu - Hold process to a maximum of this percentage CPU utilization.
  • pid - The process to throttle.
  • session_id - The session to throttle.

The max_cpu argument is required. The pid and session_id arguments can be inferred from the session_id in the when clause and are normally omitted.

host:pg_cancel_backend

Cancel a query on a host. This action calls the PostgreSQL pg_cancel_backend administrative function.

Arguments:

  • session_id – The session ID of the query to terminate.

The argument is normally omitted, allowing the session ID to be inferred by using the session_id in the rule’s when clause. Workload Manager then determines which session to cancel. The action sends a SIGINT signal to the session process, which cancels the current query. See http://www.postgresql.org/docs/9.3/static/functions-admin.html for more details.

The following example cancels the current query in any session that has been executing for more than 20 seconds:

mdw/gpdb-cluster> rule add cancel_query host:pg_cancel_backend()
when session_id:host:pid:runtime > 20

pg_terminate_backend

Terminate a session on all hosts. This action calls the PostgreSQL pg_terminate_backend administrative function.

Arguments:

  • session_id – The session ID to terminate.

The argument is normally omitted, allowing the session ID to be inferred by using the session_id matched by rule’s when clause. Workload Manager then determines which pid to terminate. See http://www.postgresql.org/docs/9.3/static/functions-admin.html for more details.

The following example terminates any session that has been executing for more than 20 seconds:

mdw/gpdb-cluster> rule add cancel_session pg_terminate_backend()
when session_id:host:pid:runtime > 20

gpdb_record

Logs a message to the gp_wlm_records table when a rule is matched.

Arguments:

  • message – Informative string describing the reason for recording.

The following example logs all queries:

mdw/gpdb_cluster> rule add record_query gpdb_record(message="all") when session_id:host:pid:usename =~ /.*/

See Querying the gp_wlm_records Table for information about the gp_wlm_records table.