293 lines
9.2 KiB
Markdown
293 lines
9.2 KiB
Markdown
---
|
|
layout: default
|
|
title: Command flags
|
|
nav_order: 51
|
|
parent: Command reference
|
|
redirect_from: /benchmark/commands/command-flags/
|
|
grand_parent: OpenSearch Benchmark Reference
|
|
---
|
|
|
|
# Command flags
|
|
OpenSearch Benchmark uses command line flags to change Benchmark's behavior. Not all flags can be used with each command. To find out which flags are supported by a specific command, enter `opensearch-benchmark <command> --h`.
|
|
|
|
All command flags are added to a command using the following syntax:
|
|
|
|
```bash
|
|
opensearch-benchmark <command> --<command-flag>
|
|
```
|
|
|
|
Flags that accept comma-separated values, such `--telemetry`, can also accept a JSON array. This can be defined by passing a file path ending in `.json` or inline as a JSON string.
|
|
|
|
- Comma-seperated values: `opensearch-benchmark ... --test-procedure="ingest-only,search-aggregations"`
|
|
- JSON file: `opensearch-benchmark ... --workload-params="params.json"`
|
|
- JSON inline string: `opensearch-benchmark ... --telemetry='["node-stats", "recovery-stats"]'`
|
|
|
|
<!-- vale off -->
|
|
## workload-path
|
|
<!-- vale on -->
|
|
|
|
This can be either a directory that contains a `workload.json` file or a `.json` file with an arbitrary name that contains a workload specification. `--workload-path` and `--workload-repository` as well as `--workload` are mutually exclusive.
|
|
|
|
<!-- vale off -->
|
|
## workload-repositor
|
|
<!-- vale on -->
|
|
|
|
This defines the repository from which OpenSearch Benchmark loads workloads. `--workload-path` and `--workload-repository` as well as `--workload` are mutually exclusive.
|
|
|
|
<!-- vale off -->
|
|
## workload-revision
|
|
<!-- vale on -->
|
|
|
|
Defines a specific revision from the workload source tree that OpenSearch Benchmark should use.
|
|
|
|
<!-- vale off -->
|
|
## workload
|
|
<!-- vale on -->
|
|
|
|
Defines the workload to use based on the workload's name. You can find a list of preloaded workloads using `opensearch-benchmark list workloads`. `--workload-path` and `--workload-repository` as well as `--workload` are mutually exclusive.
|
|
|
|
<!-- vale off -->
|
|
## workload-params
|
|
<!-- vale on -->
|
|
|
|
Defines which variables to inject into the workload. Variables injected must be available in the workload. To see which parameters are valid in the official workloads, select the workload from [the workloads repository](https://github.com/opensearch-project/opensearch-benchmark-workloads).
|
|
|
|
<!-- vale off -->
|
|
## test-procedure
|
|
<!-- vale on -->
|
|
|
|
Defines the test procedures to use with each workload. You can find a list of test procedures that the workload supports by specifying the workload in the `info` command, for example, `opensearch-benchmark info --workload=<workload_name>`. To look up information on a specific test procedure, use the command `opensearch-benchmark info --workload=<workload_name> --test-procedure=<test-procedure>`.
|
|
|
|
<!-- vale off -->
|
|
## test-execution-id
|
|
<!-- vale on -->
|
|
|
|
Defines a unique ID for the test run.
|
|
|
|
<!-- vale off -->
|
|
## include-tasks
|
|
<!-- vale on -->
|
|
|
|
Defines a comma-separated list of test procedure tasks to run. By default, all tasks listed in a test procedure array are run.
|
|
|
|
Tests are executed in the order they are defined in `test-procedure`---not in the order they are defined in the command.
|
|
|
|
All task filters are case sensitive.
|
|
|
|
<!-- vale off -->
|
|
## exclude-tasks
|
|
<!-- vale on -->
|
|
|
|
Defines a comma-separated list of test procedure tasks not to run.
|
|
|
|
<!-- vale off -->
|
|
## baseline
|
|
<!-- vale on -->
|
|
|
|
The baseline TestExecution ID used to compare the contender TestExecution.
|
|
|
|
<!-- vale off -->
|
|
## contender
|
|
<!-- vale on -->
|
|
|
|
The TestExecution ID for the contender being compared to the baseline.
|
|
|
|
<!-- vale off -->
|
|
## results-format
|
|
<!-- vale on -->
|
|
|
|
Defines the output format for the command line results, either `markdown` or `csv`. Default is `markdown`.
|
|
|
|
|
|
<!-- vale off -->
|
|
## results-number-align
|
|
<!-- vale on -->
|
|
|
|
Defines the column number alignment for when the `compare` command outputs results. Default is `right`.
|
|
|
|
<!-- vale off -->
|
|
## results-file
|
|
<!-- vale on -->
|
|
|
|
When provided a file path, writes the compare results to the file indicated in the path.
|
|
|
|
<!-- vale off -->
|
|
## show-in-results
|
|
<!-- vale on -->
|
|
|
|
Determines whether or not to include the comparison in the results file.
|
|
|
|
<!-- vale off -->
|
|
## provision-config-repository
|
|
<!-- vale on -->
|
|
|
|
Defines the repository from which OpenSearch Benchmark loads `provision-configs` and `provision-config-instances`.
|
|
|
|
<!-- vale off -->
|
|
## provision-config-revision
|
|
<!-- vale on -->
|
|
|
|
Defines the specific Git revision in the `provision-config` that OpenSearch Benchmark should use.
|
|
|
|
<!-- vale off -->
|
|
## provision-config-path
|
|
<!-- vale on -->
|
|
|
|
Defines the path to the `--provision-config-instance` and any OpenSearch plugin configurations to use.
|
|
|
|
<!-- vale off -->
|
|
## distribution-version
|
|
<!-- vale on -->
|
|
|
|
Downloads the specified OpenSearch distribution based on version number. For a list of released OpenSearch versions, see [Version history](https://opensearch.org/docs/version-history/).
|
|
|
|
<!-- vale off -->
|
|
## distribution-repository
|
|
<!-- vale on -->
|
|
|
|
Defines the repository from which the OpenSearch distribution should be downloaded. Default is `release`.
|
|
|
|
<!-- vale off -->
|
|
## provision-config-instance
|
|
<!-- vale on -->
|
|
|
|
Defines the `--provision-config-instance` to use. You can view possible configuration instances by using the command `opensearch-benchmark list provision-config-instances`.
|
|
|
|
<!-- vale off -->
|
|
## provision-config-instance-params
|
|
<!-- vale on -->
|
|
|
|
A comma-separated list of key-value pairs injected verbatim as variables for the `provision-config-instance`.
|
|
|
|
<!-- vale off -->
|
|
## target-hosts
|
|
<!-- vale on -->
|
|
|
|
Defines a comma-separated list of host-port pairs that should be targeted if using the pipeline `benchmark-only`. Default is `localhost:9200`.
|
|
|
|
<!-- vale off -->
|
|
## target-os
|
|
<!-- vale on -->
|
|
|
|
The target operating system (OS) for which the OpenSearch artifact should be downloaded. Default is the current OS.
|
|
|
|
<!-- vale off -->
|
|
## target-arch
|
|
<!-- vale on -->
|
|
|
|
The name of the CPU architecture for which an artifact should be downloaded.
|
|
|
|
<!-- vale off -->
|
|
## revision
|
|
<!-- vale on -->
|
|
|
|
Defines the current source code revision to use for running a benchmark test. Default is `current`.
|
|
|
|
This command flag can use the following options:
|
|
|
|
- `current`: Uses the source tree's current revision based on your OpenSearch distribution.
|
|
- `latest`: Fetches the latest revision from the main branch of the source tree.
|
|
|
|
You can also use a timestamp or commit ID from the source tree. When using a timestamp, specify `@ts`, where "ts" is a valid ISO 8601 timestamp, for example, `@2013-07-27T10:37:00Z`.
|
|
|
|
<!-- vale off -->
|
|
## opensearch-plugins
|
|
<!-- vale on -->
|
|
|
|
Defines which [OpenSearch plugins]({{site.url}}{{site.baseurl}}/install-and-configure/plugins/) to install. By default, no plugins are installed.
|
|
|
|
<!-- vale off -->
|
|
## plugin-params
|
|
<!-- vale on -->
|
|
|
|
Defines a comma-separated list of key-value pairs that are injected verbatim into all plugins as variables.
|
|
|
|
<!-- vale off -->
|
|
## runtime-jdk
|
|
<!-- vale on -->
|
|
|
|
The major version of JDK to use.
|
|
|
|
|
|
<!-- vale off -->
|
|
## client-options
|
|
<!-- vale on -->
|
|
|
|
Defines a comma-separated list of clients to use. All options are passed to the OpenSearch Python client. Default is `timeout:60`.
|
|
|
|
<!-- vale off -->
|
|
## load-worker-coordinator-hosts
|
|
<!-- vale on -->
|
|
|
|
Defines a comma-separated list of hosts that coordinate loads. Default is `localhost`.
|
|
|
|
<!-- vale off -->
|
|
## enable-worker-coordinator-profiling
|
|
<!-- vale on -->
|
|
|
|
Enables a performance analysis of OpenSearch Benchmark's worker coordinator. Default is `false`.
|
|
|
|
<!-- vale off -->
|
|
## pipeline
|
|
<!-- vale on -->
|
|
|
|
The `--pipeline` option selects a pipeline to run. You can find a list of pipelines supported by OpenSearch Benchmark by running `opensearch-benchmark list pipelines`.
|
|
|
|
<!-- vale off -->
|
|
## telemetry
|
|
<!-- vale on -->
|
|
|
|
Enables the provided telemetry devices when the devices are provided using a comma-separated list. You can find a list of possible telemetry devices by using `opensearch-benchmark list telemetry`.
|
|
|
|
<!-- vale off -->
|
|
## telemetry-params
|
|
<!-- vale on -->
|
|
|
|
Enables setting parameters for telemetry devices. Accepts a list of comma-separated key-value pairs, each of which are delimited by a colon or a JSON file name.
|
|
|
|
<!-- vale off -->
|
|
## on-error
|
|
<!-- vale on -->
|
|
|
|
Controls how OpenSearch Benchmark responds to errors. Default is `continue`.
|
|
|
|
You can use the following options with this command flag:
|
|
|
|
- `continue`: Continues to run the test despite the error.
|
|
- `abort`: Aborts the test when an error occurs.
|
|
|
|
<!-- vale off -->
|
|
## preserve-install
|
|
<!-- vale on -->
|
|
|
|
Keeps the Benchmark candidate and its index. Default is `false`.
|
|
|
|
<!-- vale off -->
|
|
## kill-running-processes
|
|
<!-- vale on -->
|
|
|
|
When set to `true`, stops any OpenSearch Benchmark processes currently running and allows Benchmark to continue to run. Default is `false`.
|
|
|
|
<!-- vale off -->
|
|
## chart-spec-path
|
|
<!-- vale on -->
|
|
|
|
Sets the path to the JSON files containing chart specifications that can be used to generate charts.
|
|
|
|
<!-- vale off -->
|
|
## chart-type
|
|
<!-- vale on -->
|
|
|
|
Generates the indicated chart type, either `time-series` or `bar`. Default is `time-series`.
|
|
|
|
<!-- vale off -->
|
|
## output-path
|
|
<!-- vale on -->
|
|
|
|
The name and path used for the chart's output. Default is `stdout`.
|
|
|
|
<!-- vale off -->
|
|
## limit
|
|
<!-- vale on -->
|
|
|
|
Limits the number of search results for recent test runs. Default is `10`. |