Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 22. Benchmarking command-line client

The rally client is a command-line interface (CLI) tool that automates and unifies multi-node OpenStack deployment, cloud verification, benchmarking, and profiling. This chapter documents rally version 0.3.3.
For help on a specific rally command, enter: 
$ rally-manage COMMAND --help
Copy to Clipboard Toggle word wrap
Or: 
$ rally COMMAND --help
Copy to Clipboard Toggle word wrap

22.1. rally usage
Copy link

usage: rally [-h] [--config-dir DIR] [--config-file PATH] [--debug] [--log-config-append PATH] [--log-date-format DATE_FORMAT] [--log-dir LOG_DIR] [--log-file PATH] [--nodebug] [--norally-debug] [--nouse-syslog] [--noverbose] [--nowatch-log-file] [--plugin-paths PLUGIN_PATHS] [--rally-debug] [--syslog-log-facility SYSLOG_LOG_FACILITY] [--use-syslog] [--verbose] [--version] [--watch-log-file] {version,bash-completion,show,task,plugin,verify,deployment} ...
Copy to Clipboard Toggle word wrap

22.2. rally optional arguments
Copy link

-h, --help
show this help message and exit
--config-dir DIR
Path to a config directory to pull *.conf files from. This file set is sorted, so as to provide a predictable parse order if individual options are over-ridden. The set is parsed after the file(s) specified via previous --config-file, arguments hence over-ridden options in the directory take precedence.
--config-file PATH
Path to a config file to use. Multiple config files can be specified, with values in later files taking precedence. Defaults to None.
--debug, -d
If set to true, the logging level will be set to DEBUG instead of the default INFO level.
--log-config-append PATH, --log_config PATH
The name of a logging configuration file. This file is appended to any existing logging configuration files. For details about logging configuration files, see the Python logging module documentation. Note that when logging configuration files are used then all logging configuration is set in the configuration file and other logging configuration options are ignored (for example, logging_context_format_string).
--log-date-format DATE_FORMAT
Defines the format string for %(asctime)s in log records. Default: None . This option is ignored if log_config_append is set.
--log-dir LOG_DIR, --logdir LOG_DIR
(Optional) The base directory used for relative log_file paths. This option is ignored if log_config_append is set.
--log-file PATH, --logfile PATH
(Optional) Name of log file to send logging output to. If no default is set, logging will go to stderr as defined by use_stderr. This option is ignored if log_config_append is set.
--nodebug
The inverse of --debug
--norally-debug
The inverse of --rally-debug
--nouse-syslog
The inverse of --use-syslog
--noverbose
The inverse of --verbose
--nowatch-log-file
The inverse of --watch-log-file
--plugin-paths PLUGIN_PATHS
Additional custom plugin locations. Multiple files or directories may be specified. All plugins in the specified directories and subdirectories will be imported. Plugins in /opt/rally/plugins and ~/.rally/plugins will always be imported.
--rally-debug
Print debugging output only for Rally. Off-site components stay quiet.
--syslog-log-facility SYSLOG_LOG_FACILITY
Syslog facility to receive log lines. This option is ignored if log_config_append is set.
--use-syslog
Use syslog for logging. Existing syslog format is DEPRECATED and will be changed later to honor RFC5424. This option is ignored if log_config_append is set.
--verbose, -v
If set to false, the logging level will be set to WARNING instead of the default INFO level.
--version
show program's version number and exit
--watch-log-file
Uses logging handler designed to watch file system. When log file is moved or removed this handler will open a new log file with specified path instantaneously. It makes sense only if log_file option is specified and Linux platform is used. This option is ignored if log_config_append is set.

22.3. Category: db
Copy link

Commands for DB management.

22.3.1. rally-manage db create
Copy link

Create Rally database.

22.3.2. rally-manage db downgrade
Copy link

Downgrade Rally database.
Command arguments:
--revision <revision>
Downgrade to specified revision UUID. Current revision of DB could be found by calling rally-manage db revision.

22.3.3. rally-manage db recreate
Copy link

Drop and create Rally database.
This will delete all existing data.

22.3.4. rally-manage db revision
Copy link

Print current Rally database revision UUID.

22.3.5. rally-manage db upgrade
Copy link

Upgrade Rally database to the latest state.

22.4. Category: deployment
Copy link

Set of commands that allow you to manage deployments.

22.4.1. rally deployment check
Copy link

Check keystone authentication and list all available services.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of the deployment.
Type: str

22.4.2. rally deployment config
Copy link

Display configuration of the deployment.
Output is the configuration of the deployment in a pretty-printed JSON format.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of the deployment.
Type: str

22.4.3. rally deployment create
Copy link

Create new deployment.
This command will create a new deployment record in rally database. In the case of ExistingCloud deployment engine it will use the cloud represented in the configuration. If the cloud doesn't exist, Rally can deploy a new one for you with Devstack or Fuel. Different deployment engines exist for these cases.
If you use the ExistingCloud deployment engine you can pass a deployment config by environment variables with --fromenv:
OS_USERNAME OS_PASSWORD OS_AUTH_URL OS_TENANT_NAME OS_ENDPOINT_TYPE or OS_INTERFACE OS_ENDPOINT OS_REGION_NAME OS_CACERT OS_INSECURE
All other deployment engines need more complex configuration data, so it should be stored in a configuration file.
You can use physical servers, LXC containers, KVM virtual machines or virtual machines in OpenStack for deploying the cloud. Except physical servers, Rally can create cluster nodes for you. Interaction with virtualization software, OpenStack cloud or physical servers is provided by server providers.
Command arguments:
--name <name>
Name of the deployment.
Type: str
--fromenv
Read environment variables instead of config file.
--filename <path>
Path to the configuration file of the deployment.
Type: str
Default: None
--no-use
Don't set new deployment as default for future operations.

22.4.4. rally deployment destroy
Copy link

Destroy existing deployment.
This will delete all containers, virtual machines, OpenStack instances or Fuel clusters created during Rally deployment creation. Also it will remove the deployment record from the Rally database.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of the deployment.
Type: str

22.4.5. rally deployment list
Copy link

List existing deployments.

22.4.6. rally deployment recreate
Copy link

Destroy and create an existing deployment.
Unlike 'deployment destroy', the deployment database record will not be deleted, so the deployment UUID stays the same.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of the deployment.
Type: str

22.4.7. rally deployment show
Copy link

Show the credentials of the deployment.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of the deployment.
Type: str

22.4.8. rally deployment use
Copy link

Set active deployment.
Command arguments:
--deployment <uuid>
UUID or name of a deployment.
Type: str

22.5. Category: plugin
Copy link

Set of commands that allow you to manage Rally plugins.

22.5.1. rally plugin list
Copy link

List all Rally plugins that match name and namespace.
Command arguments:
--name <name>
List only plugins that match the given name.
Type: str
Default: None
--namespace <namespace>
List only plugins that are in the specified namespace.
Type: str
Default: None

22.5.2. rally plugin show
Copy link

Show detailed information about a Rally plugin.
Command arguments:
--name <name>
Plugin name.
Type: str
--namespace <namespace>
Plugin namespace.
Type: str
Default: None

22.6. Category: show
Copy link

Warning
Deprecated since 0.2.0
Show resources.
Set of commands that allow you to view resources, provided by OpenStack cloud represented by deployment.

22.6.1. rally show flavors
Copy link

Display available flavors.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of a deployment.
Type: str

22.6.2. rally show images
Copy link

Display available images.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of a deployment.
Type: str

22.6.3. rally show keypairs
Copy link

Display available ssh keypairs.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of a deployment.
Type: str

22.6.4. rally show networks
Copy link

Display configured networks.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of a deployment.
Type: str

22.6.5. rally show secgroups
Copy link

Display security groups.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of a deployment.
Type: str

22.7. Category: task
Copy link

Set of commands that allow you to manage benchmarking tasks and results.

22.7.1. rally task abort
Copy link

Abort a running benchmarking task.
Command arguments:
--uuid <uuid>
UUID of task.
Type: str
--soft
Abort task after current scenario finishes execution.

22.7.2. rally task delete
Copy link

Delete task and its results.
Command arguments:
--force
force delete
--uuid <task-id>
UUID of task or a list of task UUIDs.
Type: str

22.7.3. rally task detailed
Copy link

Print detailed information about given task.
Command arguments:
--uuid <uuid>
UUID of task. If --uuid is "last" the results of the most recently created task will be displayed.
Type: str
--iterations-data
Print detailed results for each iteration.

22.7.4. rally task export
Copy link

Export task results to the custom task's exporting system.
Command arguments:
--uuid <uuid>
UUID of a the task.
Type: str
--connection <connection>
Connection url to the task export system.
Type: str

22.7.5. rally task list
Copy link

List tasks, started and finished.
Displayed tasks can be filtered by status or deployment. By default 'rally task list' will display tasks from the active deployment without filtering by status.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of a deployment.
Type: str
--all-deployments
List tasks from all deployments.
--status <status>
List tasks with specified status. Available statuses: aborted, aborting, cleaning up, failed, finished, init, paused, running, setting up, soft_aborting, verifying
Type: str
Default: None
--uuids-only
List task UUIDs only.

22.7.6. rally task report
Copy link

Generate report file for specified task.
Command arguments:
--tasks <tasks>
UUIDs of tasks, or JSON files with task results
Default: None
--out <path>
Path to output file.
Type: str
Default: None
--open
Open the output in a browser.
--html
Generate the report in HTML.
--html-static
Generate the report in HTML with embedded JS and CSS, so it will not depend on Internet availability.
--junit
Generate the report in the JUnit format.

22.7.7. rally task results
Copy link

Display raw task results.
This will produce a lot of output data about every iteration.
Command arguments:
--uuid <uuid>
UUID of task.
Type: str

22.7.8. rally task sla_check
Copy link

Display SLA check results table.
Command arguments:
--uuid <uuid>
UUID of task.
Type: str
--json
Output in JSON format.

22.7.9. rally task start
Copy link

Start benchmark task.
If both task_args and task_args_file are specified, they will be merged. task_args has a higher priority so it will override values from task_args_file.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of a deployment.
Type: str
--task <path>, --filename <path>
Note
The default value for the --task argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally task start, if the --no-use argument was not used.
Tip
You can set the default value by executing rally task use <uuid>.
Path to the input task file
--task-args <json>
Input task args (JSON dict). These args are used to render the Jinja2 template in the input task.
Default: None
--task-args-file <path>
Path to the file with input task args (dict in JSON/YAML). These args are used to render the Jinja2 template in the input task.
Default: None
--tag <tag>
Tag for this task
Default: None
--no-use
Don't set new task as default for future operations.
--abort-on-sla-failure
Abort the execution of a benchmark scenario whenany SLA check for it fails.

22.7.10. rally task status
Copy link

Display the current status of a task.
Command arguments:
--uuid <uuid>
UUID of task
Type: str

22.7.12. rally task use
Copy link

Set active task.
Command arguments:
--uuid <uuid>
UUID of the task
Type: str
--task
[Deprecated since Rally 0.2.0] Use '--uuid' instead.
Type: str

22.7.13. rally task validate
Copy link

Validate a task configuration file.
This will check that task configuration file has valid syntax and all required options of scenarios, contexts, SLA and runners are set.
If both task_args and task_args_file are specified, they will be merged. task_args has a higher priority so it will override values from task_args_file.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Hint
You can set the default value by executing rally deployment use <uuid>.
UUID or name of a deployment.
Type: str
--task <path>, --filename <path>
Note
The default value for the --task argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally task start, if the --no-use argument was not used.
Hint
You can set the default value by executing rally task use <uuid>.
Path to the input task file.
--task-args <json>
Input task args (JSON dict). These args are used to render the Jinja2 template in the input task.
Default: None
--task-args-file <path>
Path to the file with input task args (dict in JSON/YAML). These args are used to render the Jinja2 template in the input task.
Default: None

22.8. Category: verify
Copy link

Verify an OpenStack cloud via Tempest.
Set of commands that allow you to run Tempest tests.

22.8.1. rally verify compare
Copy link

Compare two verification results.
Command arguments:
--uuid-1 <uuid_1>
UUID of the first verification
Type: str
Default: None
--uuid-2 <uuid_2>
UUID of the second verification
Type: str
Default: None
--csv
Display results in CSV format
--html
Display results in HTML format
--json
Display results in JSON format
--output-file <output_file>
Path to a file to save results
Type: str
Default: None
--threshold <threshold>
If specified, timing differences must exceed this percentage threshold to be included in output
Type: int
Default: 0

22.8.2. rally verify detailed
Copy link

Display results table of a verification with detailed errors.
Command arguments:
--uuid <uuid>
Note
The default value for the --uuid argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally verify start, rally verify import_results, if the --no-use argument was not used.
Tip
You can set the default value by executing rally verify use <uuid>.
UUID of a verification.
Type: str
--sort-by <sort_by>
Sort results by 'name' or 'duration'
Default: name

22.8.3. rally verify discover
Copy link

Show a list of discovered tests.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of a deployment
Type: str
--pattern <pattern>
Test name pattern which can be used to match
Type: str
Default:

22.8.4. rally verify genconfig
Copy link

Generate Tempest configuration file.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of a deployment.
Type: str
--tempest-config <path>
User-specified Tempest config file location
Type: str
Default: None
--override
Override existing Tempest config file

22.8.5. rally verify import
Copy link

Import Tempest tests results into the Rally database.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of a deployment.
Type: str
--set <set_name>
Name of a Tempest test set. Available sets are full, scenario, smoke, baremetal, clustering, compute, database, data_processing, identity, image, messaging, network, object_storage, orchestration, telemetry, volume
Type: str
Default:
--file <path>
User specified Tempest log file location. Note, Tempest log file needs to be in subunit format
Type: str
Default: None
--no-use
Don't set new task as default for future operations

22.8.6. rally verify install
Copy link

Install Tempest.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of a deployment.
Type: str
--source <source>
Path/URL to repo to clone Tempest from
Type: str
Default: None
--version <version>
Commit ID or tag to checkout before Tempest installation
Type: str
Default: None
--system-wide
Don't create a virtual env for Tempest. Note that all Tempest requirements have to be already installed in the local env!

22.8.7. rally verify list
Copy link

List verification runs.

22.8.8. rally verify reinstall
Copy link

Uninstall Tempest and install again.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of a deployment.
Type: str
--source <source>
Path/URL to repo to clone Tempest from
Type: str
Default: None
--version <version>
Commit ID or tag to checkout before Tempest installation
Type: str
Default: None
--system-wide
Don't create a virtual env for Tempest. Note that all Tempest requirements have to be already installed in the local env!

22.8.9. rally verify results
Copy link

Display results of a verification.
Command arguments:
--uuid <uuid>
Note
The default value for the --uuid argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally verify start, rally verify import_results, if the --no-use argument was not used.
Tip
You can set the default value by executing rally verify use <uuid>.
UUID of a verification.
Type: str
--html
Display results in HTML format.
--json
Display results in JSON format.
--output-file <path>
Path to a file to save results to.
Type: str
Default: None

22.8.10. rally verify show
Copy link

Display results table of a verification.
Command arguments:
--uuid <uuid>
Note
The default value for the --uuid argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally verify start, rally verify import_results, if the --no-use argument was not used.
Tip
You can set the default value by executing rally verify use <uuid>.
UUID of a verification
Type: str
--sort-by <query>
Sort results by 'name' or 'duration'
Type: str
Default: name
--detailed
Display detailed errors of failed tests

22.8.11. rally verify showconfig
Copy link

Show configuration file of Tempest.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of a deployment.
Type: str

22.8.12. rally verify start
Copy link

Start verification (run Tempest tests).
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of a deployment.
Type: str
--set <set_name>
Name of a Tempest test set. Available sets are full, scenario, smoke, baremetal, clustering, compute, database, data_processing, identity, image, messaging, network, object_storage, orchestration, telemetry, volume
Type: str
Default:
--regex <regex>
Test name regular expression
Type: str
Default: None
--tests-file <path>
Path to a file with a list of Tempest tests
Type: str
Default: None
--tempest-config <path>
User-specified Tempest config file location
Type: str
Default: None
--xfails-file <path>
Path to a YAML file with a list of Tempest tests that are expected to fail
Type: str
Default: None
--no-use
Don't set the task as default for future operations
--system-wide
Don't create a virtual env when installing Tempest; use the local env instead of the Tempest virtual env when running the tests. Note that all Tempest requirements have to be already installed in the local env!
--concurrency N
How many processes to use to run Tempest tests. The default value (0) auto-detects your CPU count
Type: int
Default: 0
--failing
Re-run the tests that failed in the last execution

22.8.13. rally verify uninstall
Copy link

Remove the deployment's local Tempest installation.
Command arguments:
--deployment <uuid>
Note
The default value for the --deployment argument is taken from the Rally environment. Usually, the default value is equal to the UUID of the last successful run of rally deployment create, if the --no-use argument was not used.
Tip
You can set the default value by executing rally deployment use <uuid>.
UUID or name of a deployment.
Type: str

22.8.14. rally verify use
Copy link

Set active verification.
Command arguments:
--uuid <uuid>
UUID of a verification
Type: str
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat