Running a workload
Once you have a complete understanding of the various components of an OpenSearch Benchmark workload, you can run your first workload.
Step 1: Find the workload name
To learn more about the standard workloads included with OpenSearch Benchmark, use the following command:
opensearch-benchmark list workloads
A list of all workloads supported by OpenSearch Benchmark appears. Review the list and select the workload that’s most similar to your cluster’s use case.
Step 2: Running the test
After you’ve selected the workload, you can invoke the workload using the opensearch-benchmark execute-test command. Replace --target-host with the host:port pairs for your cluster and --client-options with any authorization options required to access the cluster. The following example runs the nyc_taxis workload on a localhost for testing purposes.
If you want to run a test on an external cluster, see Running the workload on your own cluster.
opensearch-benchmark execute-test --pipeline=benchmark-only --workload=nyc_taxis --target-host=https://localhost:9200 --client-options=basic_auth_user:admin,basic_auth_password:admin,verify_certs:false
Results from the test appear in the directory set by the --output-path option in the execute-test command.
Test mode
If you want to run the test in test mode to make sure that your workload operates as intended, add the --test-mode option to the execute-test command. Test mode ingests only the first 1,000 documents from each index provided and runs query operations against them.
Step 3: Validate the test
After running an OpenSearch Benchmark test, take the following steps to verify that it has run properly:
- Note the number of documents in the OpenSearch or OpenSearch Dashboards index that you plan to run the benchmark against.
- In the results returned by OpenSearch Benchmark, compare the
workload.jsonfile for your specific workload and verify that the document count matches the number of documents. For example, based on the nyc_taxisworkload.jsonfile, you should expect to see165346692documents in your cluster.
Expected results
OSB returns the following response once the benchmark completes:
------------------------------------------------------
_______ __ _____
/ ____(_)___ ____ _/ / / ___/_________ ________
/ /_ / / __ \/ __ `/ / \__ \/ ___/ __ \/ ___/ _ \
/ __/ / / / / / /_/ / / ___/ / /__/ /_/ / / / __/
/_/ /_/_/ /_/\__,_/_/ /____/\___/\____/_/ \___/
------------------------------------------------------
| Metric | Task | Value | Unit |
|---------------------------------------------------------------:|-------------------------------------------:|------------:|-------:|
| Cumulative indexing time of primary shards | | 0.02655 | min |
| Min cumulative indexing time across primary shards | | 0 | min |
| Median cumulative indexing time across primary shards | | 0.00176667 | min |
| Max cumulative indexing time across primary shards | | 0.0140333 | min |
| Cumulative indexing throttle time of primary shards | | 0 | min |
| Min cumulative indexing throttle time across primary shards | | 0 | min |
| Median cumulative indexing throttle time across primary shards | | 0 | min |
| Max cumulative indexing throttle time across primary shards | | 0 | min |
| Cumulative merge time of primary shards | | 0.0102333 | min |
| Cumulative merge count of primary shards | | 3 | |
| Min cumulative merge time across primary shards | | 0 | min |
| Median cumulative merge time across primary shards | | 0 | min |
| Max cumulative merge time across primary shards | | 0.0102333 | min |
| Cumulative merge throttle time of primary shards | | 0 | min |
| Min cumulative merge throttle time across primary shards | | 0 | min |
| Median cumulative merge throttle time across primary shards | | 0 | min |
| Max cumulative merge throttle time across primary shards | | 0 | min |
| Cumulative refresh time of primary shards | | 0.0709333 | min |
| Cumulative refresh count of primary shards | | 118 | |
| Min cumulative refresh time across primary shards | | 0 | min |
| Median cumulative refresh time across primary shards | | 0.00186667 | min |
| Max cumulative refresh time across primary shards | | 0.0511667 | min |
| Cumulative flush time of primary shards | | 0.00963333 | min |
| Cumulative flush count of primary shards | | 4 | |
| Min cumulative flush time across primary shards | | 0 | min |
| Median cumulative flush time across primary shards | | 0 | min |
| Max cumulative flush time across primary shards | | 0.00398333 | min |
| Total Young Gen GC time | | 0 | s |
| Total Young Gen GC count | | 0 | |
| Total Old Gen GC time | | 0 | s |
| Total Old Gen GC count | | 0 | |
| Store size | | 0.000485923 | GB |
| Translog size | | 2.01873e-05 | GB |
| Heap used for segments | | 0 | MB |
| Heap used for doc values | | 0 | MB |
| Heap used for terms | | 0 | MB |
| Heap used for norms | | 0 | MB |
| Heap used for points | | 0 | MB |
| Heap used for stored fields | | 0 | MB |
| Segment count | | 32 | |
| Min Throughput | index | 3008.97 | docs/s |
| Mean Throughput | index | 3008.97 | docs/s |
| Median Throughput | index | 3008.97 | docs/s |
| Max Throughput | index | 3008.97 | docs/s |
| 50th percentile latency | index | 351.059 | ms |
| 100th percentile latency | index | 365.058 | ms |
| 50th percentile service time | index | 351.059 | ms |
| 100th percentile service time | index | 365.058 | ms |
| error rate | index | 0 | % |
| Min Throughput | wait-until-merges-finish | 28.41 | ops/s |
| Mean Throughput | wait-until-merges-finish | 28.41 | ops/s |
| Median Throughput | wait-until-merges-finish | 28.41 | ops/s |
| Max Throughput | wait-until-merges-finish | 28.41 | ops/s |
| 100th percentile latency | wait-until-merges-finish | 34.7088 | ms |
| 100th percentile service time | wait-until-merges-finish | 34.7088 | ms |
| error rate | wait-until-merges-finish | 0 | % |
| Min Throughput | percolator_with_content_president_bush | 36.09 | ops/s |
| Mean Throughput | percolator_with_content_president_bush | 36.09 | ops/s |
| Median Throughput | percolator_with_content_president_bush | 36.09 | ops/s |
| Max Throughput | percolator_with_content_president_bush | 36.09 | ops/s |
| 100th percentile latency | percolator_with_content_president_bush | 35.9822 | ms |
| 100th percentile service time | percolator_with_content_president_bush | 7.93048 | ms |
| error rate | percolator_with_content_president_bush | 0 | % |
[...]
| Min Throughput | percolator_with_content_ignore_me | 16.1 | ops/s |
| Mean Throughput | percolator_with_content_ignore_me | 16.1 | ops/s |
| Median Throughput | percolator_with_content_ignore_me | 16.1 | ops/s |
| Max Throughput | percolator_with_content_ignore_me | 16.1 | ops/s |
| 100th percentile latency | percolator_with_content_ignore_me | 131.798 | ms |
| 100th percentile service time | percolator_with_content_ignore_me | 69.5237 | ms |
| error rate | percolator_with_content_ignore_me | 0 | % |
| Min Throughput | percolator_no_score_with_content_ignore_me | 29.37 | ops/s |
| Mean Throughput | percolator_no_score_with_content_ignore_me | 29.37 | ops/s |
| Median Throughput | percolator_no_score_with_content_ignore_me | 29.37 | ops/s |
| Max Throughput | percolator_no_score_with_content_ignore_me | 29.37 | ops/s |
| 100th percentile latency | percolator_no_score_with_content_ignore_me | 45.5703 | ms |
| 100th percentile service time | percolator_no_score_with_content_ignore_me | 11.316 | ms |
| error rate | percolator_no_score_with_content_ignore_me | 0 | % |
--------------------------------
[INFO] SUCCESS (took 18 seconds)
--------------------------------
Running a workload on an external cluster
Now that you’re familiar with running OpenSearch Benchmark on a local cluster, you can run it on your external cluster, as described in the following steps:
- Replace
https://localhost:9200with your target cluster endpoint. This could be a Uniform Resource Identifier (URI), such ashttps://search.mydomain.com, or aHOST:PORTspecification. - If the cluster is configured with basic authentication, replace the username and password in the command line with the appropriate credentials.
- Remove the
verify_certs:falsedirective if you are not specifyinglocalhostas your target cluster. This directive is necessary solely for clusters without SSL certificates. - If you are using a
HOST:PORTspecification and plan to use SSL or TLS, either specifyhttps://or add theuse_ssl:truedirective to the--client-optionsstring option. - Remove the
--test-modeflag to run the full workload rather than an abbreviated test.
You can copy the following command template to use it in your own terminal:
opensearch-benchmark execute-test --pipeline=benchmark-only --workload=nyc_taxis --target-host=<OpenSearch Cluster Endpoint> --client-options=basic_auth_user:admin,basic_auth_password:admin