Using the Greenplum Workload Manager Command Line

The Greenplum Workload Manager command line utility, gp-wlm, provides access to Workload Manager capabilities. The utility may be run by entering commands interactively or by specifying equivalent actions using command-line options. The command-line options are useful for scripting, since they require no interactive user input.

To get help in interactive mode, issue the command: help

To get help for command line invocation, issue the command: gp-wlm --help

Below is the gp-wlm command syntax:

Usage: gp-wlm [-g | gptop] 
            [--rule-add=[transient] <name> <rule>]
            [--rule-delete=all|<name>] [--rule-dump=<path>] [--rule-import=<path>]
            [--rule-modify=[transient] <name> <rule>] [--rule-restore=<path>]
            [--rule-show=all|<name> [<host> <domain>]]
            [--describe=<metric>]
            [--config-show <component> <setting>] [--config-describe <component> <setting>]
            [--config-modify <component> <setting>=<value>]
            [--set-domain=<domain>] [--set-host=<host>] [--schema-path=<path>] 
            [--version] [--help] [--usage]

The gp-wlm command-line options have parallel commands in the gp-wlm interactive mode. The option descriptions below link to the interactive mode commands for additional usage information and examples.

Options

-g or --gptop
Starts the gptop graphical user interface. See Using the Workload Manager Graphical Interface (gptop) for more about gptop.

--rule-add
Adds a rule to the rules engine. See Adding Rules for details about the parts of a rule and examples.

--rule-delete
Deletes a rule with a specified name or, by using the reserved name all, all current rules. See Deleting Rules for details and examples.

--rule-dump
Saves the current set of permanent rules to a named file. See Saving Rules to Disk for details and examples.

--rule-import
Adds rules saved in an external file to the current rule set. See Importing Rules for details and examples.

--rule-modify
Modifies a rule by replacing the rule expression or making a transient rule permanent. See Modifying Rules for details.

--rule-restore
Restore rules from an external file, replacing the current rules in the rulesengine. See Restoring Rules for details.

--rule-show
Display a rule by name or, by using the reserved name all, all current rules. See Displaying Rules for details and examples.

--config-show
Show the current value of a setting for a Workload Manager component. See Configuring Workload Manager Components for details about the configuration commands.

--config-describe
Describe the purpose of a setting for a Workload Manager component and its value constraints.

--config-modify
Override the value of a setting for a Workload Manager component. The component is automatically restarted after a setting is updated.

--set-domain
Set the domain, or cluster name, for the gp-wlm interactive session. It is recommended to use the default domain.

--set-host
Set the host where the gp-wlm session runs. The default is the machine where you run gp-wlm. It is recommended to only run gp-wlm on the Greenplum master host.

--schema-path
The path to the schema files. The default path, INSTALLDIR/schema, should not be changed.

--usage
Displays usage information for the gp-wlm command.

--help
Displays usage information for the gp-wlm command.

--describe
Displays a description of a metric. For example:

$ gp-wlm --describe=datid:numbackends

--version or -v
Displays the gp-wlm version.

Using gp-wlm in Interactive Mode

  1. Start gp-wlm at the command line:

    $ gp-wlm

    The gp-wlm command prompt displays the name of the host where gp-wlm is running and the name of the Greenplum Database cluster or domain.

    Enter help at the interactive prompt for a usage message.

When using the gp-wlm command-line:

  • Enter each command on a single line. Commands are executed immediately.
  • Enter the help command to view a list of Workload Manager commands.
  • Enter describe <metric> to view a description of a metric.

While entering a command, get help with command syntax by pressing the tab key to show valid options. This is especially useful when constructing a rule. In the following partial example, user entry is in bold.

mdw/gpdb-cluster> rule <tab>
add     delete  dump    modify  restore show
mdw/gpdb-cluster> rule add <tab>
<rule-name> transient
mdw/gpdb-cluster> rule add transient <tab>
          <rule-name>
mdw/gpdb-cluster> rule add transient myrule <tab>
gpdb_record       host:          pg_terminate_backend
mdw/gpdb-cluster> rule add transient myrule gpdb_record(<tab>
<dt>)                 gpdb_segment_role message           query_start       usename        </dt>
current_query     host              pid               session_id 
...

Enter the quit command at the prompt to exit the gp-wlm interactive mode.

Setting the Workload Manager Target Host and Domain

Use the set host and set domain commands to set the default host and domain for the Workload Manager session.

It is recommended to only run the gp-wlm tool on the Greenplum Database master node and to leave the host and domain at their default values.

The default host is the name of the machine where you execute gp-wlm. The host name must be resolvable in DNS. You can specify different host and cluster names on the gp-wlm command line by supplying the --set-host and --set-domain command line options.

Example:

mdw/gpdb-cluster> set host smdw
smdw/gpdb-cluster> set domain gpdbsys
smdw/gpdbsys>