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 <datum_list>]
transient
keyword to create a transient rule.
all
is reserved.
-
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 PostgreSQLhost:pg_cancel_backend()
function. -
pg_terminate_backend
– terminate a session by calling the PostgreSQLpg_terminate_backend()
function. -
gpdb_record
– record an event about a query in thegp_wlm_records
table.
arg-name=value
pair. Multiple arguments are separated by commas.
including
clause, the action context contains only values for datums referenced in the expression
clause. Add the including
clause to add values for additional datums to the action context.
Datums in the <datum_list> are specified without scope prefixes. If the Workload Manager rule compiler cannot find a datum 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 datums in <datum-list> are added to the context arguments columns in the gp_wlm_records
table or gp_wlm_events
view.
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:
-
current_query
- The text of the current query -
gpdb_segment_role
- Role of the database instance:GPDB_MASTER
orGPDB_SEGMENT
-
host
- The hostname of the segment -
message
– Informative string describing the reason for recording. -
pid
- The postgres process associated with the query -
query_start
- Query start time -
session_id
- Session id of the query -
usename
- Name of the user logged into this backend
Only the message argument must be supplied; all other arguments can be inferred from the rule’s when clause.
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 Workload Manager Record Data for information about the gp_wlm_records
table.