Merge branch 'main' into metrics-logs

_api-reference/document-apis/delete-by-query.md

@@ -48,7 +48,7 @@ default_operator | String | Indicates whether the default operator for a string
 df | String | The default field in case a field prefix is not provided in the query string.
 expand_wildcards | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are `all` (match any index), `open` (match open, non-hidden indexes), `closed` (match closed, non-hidden indexes), `hidden` (match hidden indexes), and `none` (deny wildcard expressions). Default is `open`.
 from | Integer | The starting index to search from. Default is 0.
-ignore_unavailable | Boolean | Specifies whether to include missing or closed indexes in the response. Default is false.
+ignore_unavailable | Boolean | Specifies whether to include missing or closed indexes in the response and ignores unavailable shards during the search request. Default is `false`.
 lenient | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is false.
 max_docs | Integer | How many documents the delete by query operation should process at most. Default is all documents.
 preference | String | Specifies which shard or node OpenSearch should perform the delete by query operation on.

_api-reference/document-apis/update-by-query.md

@@ -55,7 +55,7 @@ default_operator | String | Indicates whether the default operator for a string
 df | String | The default field if a field prefix is not provided in the query string.
 expand_wildcards | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are `all` (match any index), `open` (match open, non-hidden indexes), `closed` (match closed, non-hidden indexes), `hidden` (match hidden indexes), and `none` (deny wildcard expressions). Default is `open`.
 from | Integer | The starting index to search from. Default is 0.
-ignore_unavailable | Boolean | Whether to exclude missing or closed indexes in the response. Default is false.
+ignore_unavailable | Boolean | Whether to exclude missing or closed indexes in the response and ignores unavailable shards during the search request. Default is `false`.
 lenient | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is false.
 max_docs | Integer | How many documents the update by query operation should process at most. Default is all documents.
 pipeline | String | ID of the pipeline to use to process documents.

_api-reference/index-apis/stats.md

@@ -18,6 +18,7 @@ When a shard moves to a different node, the shard-level statistics for the shard
 
 ```json
 GET /_stats
+GET /_stats/<metric>
 GET /<index_ids>/_stats
 GET /<index_ids>/_stats/<metric>
 ```

_api-reference/multi-search.md

@@ -63,7 +63,7 @@ allow_no_indices | Boolean | Whether to ignore wildcards that don't match any in
 cancel_after_time_interval | Time | The time after which the search request will be canceled. Supported at both parent and child request levels. The order of precedence is:<br> 1. Child-level parameter<br> 2. Parent-level parameter<br> 3. [Cluster setting]({{site.url}}{{site.baseurl}}/api-reference/cluster-settings).<br>Default is -1. | Yes
 css_minimize_roundtrips | Boolean | Whether OpenSearch should try to minimize the number of network round trips between the coordinating node and remote clusters (only applicable to cross-cluster search requests). Default is `true`. | No
 expand_wildcards | Enum | Expands wildcard expressions to concrete indexes. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. Default is `open`. | Yes
-ignore_unavailable | Boolean | If an index from the indexes list doesn’t exist, whether to ignore it rather than fail the query. Default is `false`. | Yes
+ignore_unavailable | Boolean | If an index or shard from the indexes list doesn’t exist, whether to ignore it rather than fail the query. Default is `false`. | Yes
 max_concurrent_searches | Integer | The maximum number of concurrent searches. The default depends on your node count and search thread pool size. Higher values can improve performance, but risk overloading the cluster. | No
 max_concurrent_shard_requests | Integer | Maximum number of concurrent shard requests that each search executes per node. Default is 5. Higher values can improve performance, but risk overloading the cluster. | No
 pre_filter_shard_size | Integer | Default is 128. | No

_api-reference/script-apis/get-script-language.md

@@ -9,7 +9,7 @@ nav_order: 6
 **Introduced 1.0**
 {: .label .label-purple }
 
-The get script language API operation retrieves all supported script languages and their contexts.
+The get script language API operation retrieves all supported script languages and the contexts in which they may be used.
 
 #### Example request
 

_api-reference/search.md

@@ -56,7 +56,7 @@ expand_wildcards | String | Specifies the type of index that wildcard expression
 explain | Boolean | Whether to return details about how OpenSearch computed the document's score. Default is false.
 from | Integer | The starting index to search from. Default is 0.
 ignore_throttled | Boolean | Whether to ignore concrete, expanded, or indexes with aliases if indexes are frozen. Default is true.
-ignore_unavailable | Boolean | Specifies whether to include missing or closed indexes in the response. Default is false.
+ignore_unavailable | Boolean | Specifies whether to include missing or closed indexes in the response and ignores unavailable shards during the search request. Default is `false`.
 lenient | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is false.
 max_concurrent_shard_requests | Integer | How many concurrent shard requests this request should execute on each node. Default is 5.
 phase_took | Boolean | Whether to return phase-level `took` time values in the response. Default is false.

_automating-configurations/workflow-steps.md

@@ -25,11 +25,11 @@ The following table lists the workflow step types. The `user_inputs` fields for
 
 |Step type	|Corresponding API	|Description	|
 |---	|---	|---	|
-|`noop`	|No API	| A no-operation (no-op) step that does nothing. It may be useful in some cases for synchronizing parallel steps.	|
+| `noop` | No API | A no-operation (no-op) step that does nothing, which is useful for synchronizing parallel steps. If the `user_inputs` field contains a `delay` key, this step will wait for the specified amount of time.	|
 |`create_connector`	|[Create Connector]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/connector-apis/create-connector/)	|Creates a connector to a model hosted on a third-party platform.	|
 |`delete_connector`	|[Delete Connector]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/connector-apis/delete-connector/)	|Deletes a connector to a model hosted on a third-party platform.	|
 |`register_model_group`	|[Register Model Group]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-group-apis/register-model-group/)	|Registers a model group. The model group will be deleted automatically once no model is present in the group.	|
-|`register_remote_model`	|[Register Model (remote)]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/register-model/#register-a-model-hosted-on-a-third-party-platform)	|Registers a model hosted on a third-party platform. If the `user_inputs` field contains a `deploy` key that is set to `true`, also deploys the model.	| 
+|`register_remote_model`	|[Register Model (remote)]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/register-model/#register-a-model-hosted-on-a-third-party-platform)	| Registers a model hosted on a third-party platform. If the `user_inputs` field contains a `deploy` key that is set to `true`, the model is also deployed.	| 
 |`register_local_pretrained_model`	|[Register Model (pretrained)]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/register-model/#register-a-pretrained-text-embedding-model)	| Registers an OpenSearch-provided pretrained text embedding model that is hosted on your OpenSearch cluster. If the `user_inputs` field contains a `deploy` key that is set to `true`, also deploys the model.	|
 |`register_local_sparse_encoding_model`	|[Register Model (sparse)]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/register-model/#register-a-pretrained-sparse-encoding-model)	| Registers an OpenSearch-provided pretrained sparse encoding model that is hosted on your OpenSearch cluster. If the `user_inputs` field contains a `deploy` key that is set to `true`, also deploys the model.	|
 |`register_local_custom_model`	|[Register Model (custom)]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/register-model/#register-a-custom-model)	| Registers a custom model that is hosted on your OpenSearch cluster. If the `user_inputs` field contains a `deploy` key that is set to `true`, also deploys the model.		|
@@ -45,13 +45,14 @@ The following table lists the workflow step types. The `user_inputs` fields for
 
 ## Additional fields
 
-You can include the following additional fields in the `user_inputs` field when indicated.
+You can include the following additional fields in the `user_inputs` field if the field is supported by the indicated step type.
 
-|Field	|Data type	|Description	|
+|Field	|Data type	| Step type | Description	|
 |---	|---	|---	|
-|`node_timeout`	|Time units	|A user-provided timeout for this step. For example, `20s` for a 20-second timeout.	|
-|`deploy`	|Boolean	|Applicable to the Register Model step type. If set to `true`, also executes the Deploy Model step.	|
-|`tools_order`	|List	|Applicable only to the Register Agent step type. Specifies the ordering of `tools`. For example, specify `["foo_tool", "bar_tool"]` to sequence those tools in that order.	|
+|`node_timeout`	| Time units	| All | A user-provided timeout for this step. For example, `20s` for a 20-second timeout.	|
+|`deploy`	| Boolean	| Register model | If set to `true`, also deploys the model.	|
+|`tools_order`	| List	| Register agent | Specifies the ordering of `tools`. For example, specify `["foo_tool", "bar_tool"]` to sequence those tools in that order.	|
+|`delay`	| Time units	| No-op | Waits for the specified amount of time. For example, `250ms` specifies to wait for 250 milliseconds before continuing the workflow.	|
 
 You can include the following additional fields in the `previous_node_inputs` field when indicated.
 
@@ -61,4 +62,4 @@ You can include the following additional fields in the `previous_node_inputs` fi
 
 ## Example workflow steps
 
-For example workflow step implementations, see the [Workflow tutorial]({{site.url}}{{site.baseurl}}/automating-configurations/workflow-tutorial/).
+For example workflow step implementations, see the [Workflow tutorial]({{site.url}}{{site.baseurl}}/automating-configurations/workflow-tutorial/).

_benchmark/user-guide/concepts.md

@@ -2,9 +2,9 @@
 layout: default
 title: Concepts
 nav_order: 3
-parent: User Guide
+parent: User guide
 redirect_from: 
-  - /benchmark/user-guide/concepts/concepts/
+  - /benchmark/user-guide/concepts/
 ---
 
 # Concepts
@@ -45,7 +45,7 @@ While the definition for _throughput_ remains consistent with other client-serve
 | Metric | Common definition | **OpenSearch Benchmark definition**	|
 | :--- | :--- |:--- |
 | **Throughput** | The number of operations completed in a given period of time.	| The number of operations completed in a given period of time. |
-| **Service time**	| The amount of time that the server takes to process a request, from the point it receives the request to the point the response is returned. </br></br> It includes the time spent waiting in server-side queues but _excludes_ network latency, load balancer overhead, and deserialization/serialization. | The amount of time that it takes for `opensearch-py` to send a request and receive a response from the OpenSearch cluster. </br> </br> It includes the amount of time that it takes for the server to process a request and also _includes_ network latency, load balancer overhead, and deserialization/serialization.  |
+| **Service time**	| The amount of time that the server takes to process a request, from the point it receives the request to the point the response is returned. It includes the time spent waiting in server-side queues but _excludes_ network latency, load balancer overhead, and deserialization/serialization. | The amount of time that it takes for `opensearch-py` to send a request and receive a response from the OpenSearch cluster. It includes the amount of time that it takes for the server to process a request and also _includes_ network latency, load balancer overhead, and deserialization/serialization.  |
 | **Latency** | The total amount of time, including the service time and the amount of time that the request waits before responding. | Based on the `target-throughput` set by the user, the total amount of time that the request waits before receiving the response, in addition to any other delays that occur before the request is sent. |
 
 For more information about service time and latency in OpenSearch Benchmark, see the [Service time](#service-time) and [Latency](#latency) sections.

_benchmark/user-guide/finetine-workloads.md

@@ -0,0 +1,55 @@
+---
+layout: default
+title: Fine-tuning custom workloads
+nav_order: 12
+parent: User guide
+---
+
+# Fine-tuning custom workloads
+
+While custom workloads can help make benchmarks more specific to your application's needs, they sometimes require additional adjustments to make sure they closely resemble a production cluster.
+
+You can fine-tune your custom workloads to more closely match your benchmarking needs by using the `create-workload` feature. `create-workload` can extract documents from all indexes or specific indexes selected by the user.
+
+## Characteristics to consider 
+
+When beginning to use `create-workload` to fine-tune a custom workload, consider the following characteristics of the workload:
+
+1. **Queries** -- Consider the kinds of documents and as well as indexes targeted by the queries and the fields the queries call.
+2. **Shard Size** -- Match the shard size of the workload with the shard size of your cluster, or the benchmark will not simulate the behavior of your application. Lucene operates based on shard sizes and does not have indexes. Calculate the shard size for any index that you want to include in the custom workload.
+3. **Shard count** -- Choose the number of shards according to how you want to size the workload and improve query performance. Because each use case is different, you can determine the shard count in two ways:
+    1. Divide the ideal index size by the shard size found in step 2.
+    2. Multiply the ideal number of shards by the shard size found in step 2.
+4. **Decide how many documents to extract (Recommended)** -- Now that the shard size is set and the number of shards needed in the final index decided, you can determine how many documents you want to extract. In some cases, users aren’t interested in retrieving the entire document corpus from an index because the corpus might be too big. Instead, you might want to generate a smaller corpus. However, the corpus of the generated index should be *representative* of the index in the production workload. In other words, it should contain documents from across the index and not only from a certain area, for example, the first half of the index or the last third of the index. To decide how many documents to extract:
+    1. Multiply the number of shards by the shard size. Because every document is created unequally, add a buffer to the number---an arbitrary number of additional documents. The buffer provides assistance when the number of documents extracted is lower than the expected number, which will not help to retain your shard size. The shard size should be lower than the number of documents extracted. 
+    2. Divide the store size by the product of the previous step. The value of the multiple is used to set the number of sample documents from the reference index. 
+5. **Target cluster configuration** -- Factor the configuration and characteristics of the target cluster into how you generate the workload.
+
+
+## Example
+
+The following example contains an index named `stocks`. The `stocks` index includes documents containing statistics on all stocks being traded on the New York Stock Exchange (NYSE). OpenSearch Dashboards provides information about the `stocks` index, as shown in the following code example:
+
+```
+health status index  uuid              pri rep docs.count docs.deleted store.size pri.store.size
+green  open   stocks asjdkfjacklajldf   12   1  997818020    232823733    720gb    360gb
+```
+
+Using this information, you can start adjusting the workload to your specifications, as shown in the following steps:
+
+1. **Fetch queries associated with this index** -- Obtain the queries needed to make requests to the `stocks` index.
+2. **Find the shard size for the index** -- To get the shard size of the index, divide the store size by the number of shards in the index: `720 / (12 + (12 * 1)) = 30`. 30 GB is the shard size. You can verify this by dividing the primary store size value by the number of primary shards.
+3. **Determine the number of index shards** -- Determine the number of shards needed in the index to represent your application under a production load. For example, if you want your index to hold 300 GB of documents, but 300 GB is too much for the benchmark, determine a number that makes sense. For example, 300 GB of documents divided by the 30 GB shard size determined in the last step, or `300 / 30 = 10`, produces 10 shards. These 10 shards can either be 10 primary shards and 0 replicas, 5 primary shards and 1 replica, or 2 primary shards and 4 replicas. The shard configuration depends on your cluster's index needs.
+4. **Decide how many documents to extract** -- To retain 30 GB and have 10 shards, you need to extract at least 300 GB of documents. To determine the number of documents to extract, divide the store size value by the index size value, in this example, `720 / 300 = 2.4`. Because you want to make sure you reach a value of 30 GB per shard, it is best to round down and choose 2 as the extraction multiple, which means that OpenSearch Benchmark will extract every other document.
+5. **Think about the target cluster configuration** -- Assess the cluster you're planning to work on. Consider the use case, the size of the cluster, and the number of nodes. While fine-tuning the workload, this could be an iterative process where small adjustments to the cluster are made according to the results of the workload runs.
+
+
+## Replicating metrics
+
+In many cases, a workload will not be able to exactly replicate the exact metrics of a production cluster. However, you can aim to get as close as possible to your ideal cluster metrics by replicating the following metrics:
+
+* CPU utilization
+* Search request rates
+* Indexing rates 
+
+

_benchmark/user-guide/index.md

@@ -7,4 +7,4 @@ has_children: true
 
 # OpenSearch Benchmark User Guide
 
-The OpenSearch Benchmark User Guide includes core [concepts]({{site.url}}{{site.baseurl}}/benchmark/user-guide/concepts/concepts/), [installation]({{site.url}}{{site.baseurl}}/benchmark/installing-benchmark/) instructions, and [configuration options]({{site.url}}{{site.baseurl}}/benchmark/configuring-benchmark/) to help you get the most out of OpenSearch Benchmark.
+The OpenSearch Benchmark User Guide includes core [concepts]({{site.url}}{{site.baseurl}}/benchmark/user-guide/concepts/), [installation]({{site.url}}{{site.baseurl}}/benchmark/installing-benchmark/) instructions, and [configuration options]({{site.url}}{{site.baseurl}}/benchmark/configuring-benchmark/) to help you get the most out of OpenSearch Benchmark.

_benchmark/user-guide/target-throughput.md

@@ -2,6 +2,7 @@
 layout: default
 title: Target throughput
 nav_order: 150
+parent: User guide
 ---
 
 # Target throughput