Added target_bulk_bytes to the docs for logstash-output plugin (#7869) (

#7885)

_tools/logstash/ship-to-opensearch.md

@@ -9,7 +9,7 @@ redirect_from:
 
 # Ship events to OpenSearch
 
-You can Ship Logstash events to an OpenSearch cluster and then visualize your events with OpenSearch Dashboards.
+You can ship Logstash events to an OpenSearch cluster and then visualize your events with OpenSearch Dashboards.
 
 Make sure you have [Logstash]({{site.url}}{{site.baseurl}}/tools/logstash/index#install-logstash), [OpenSearch]({{site.url}}{{site.baseurl}}/install-and-configure/install-opensearch/index/), and [OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/index/).
 {: .note }
@@ -30,9 +30,10 @@ output {
 }
 ```
 
-
 ## Sample walkthrough
 
+The following walkthrough shows an example of how the ship a Logstash event.
+
 1.  Open the `config/pipeline.conf` file and add in the following configuration:
 
     ```yml
@@ -53,7 +54,7 @@ output {
     }
     ```
 
-    This Logstash pipeline accepts JSON input through the terminal and ships the events to an OpenSearch cluster running locally. Logstash writes the events to an index with the `logstash-logs-%{+YYYY.MM.dd}` naming convention.
+The Logstash pipeline accepts JSON input through the terminal and ships the events to an OpenSearch cluster running locally. Logstash writes the events to an index with the `logstash-logs-%{+YYYY.MM.dd}` naming convention.
 
 2. Start Logstash:
 
@@ -78,13 +79,9 @@ output {
     green | open | logstash-logs-2021.07.01 | iuh648LYSnmQrkGf70pplA | 1 | 1 | 1 | 0 | 10.3kb | 5.1kb
     ```
 
-## Adding different Authentication mechanisms in the Output plugin
-
-## auth_type to support different authentication mechanisms
+## Adding different authentication mechanisms in the Output plugin
 
-In addition to the existing authentication mechanisms, if we want to add new authentication then we will be adding them in the configuration by using auth_type
-
-Example Configuration for basic authentication:
+In addition to the existing authentication mechanisms, you can add a new authentication mechanism using the `auth_type` setting, as shown in the following example configuration:
 
 ```yml
 output {    
@@ -101,15 +98,15 @@ output {
 ```
 ### Parameters inside auth_type
 
-- type (string) - We should specify the type of authentication
-- We should add credentials required for that authentication like 'user' and 'password' for 'basic' authentication
-- We should also add other parameters required for that authentication mechanism like we added 'region' for 'aws_iam' authentication
+The following parameters are supported in the `auth_type` setting:
 
-## Configuration for AWS IAM Authentication
+- `type` (string): The type of authentication.
+- `user`: A user name.
+- `password`: The password used for basic authentication.
 
-To run the Logstash Output Opensearch plugin using aws_iam authentication, simply add a configuration following the below documentation.
+## Configuration for AWS IAM Authentication
 
-Example Configuration:
+To run the Logstash Output OpenSearch plugin using `aws_iam` authentication, add the following configuration:
 
 ```yml
 output {        
@@ -129,36 +126,41 @@ output {
 
 ### Required Parameters
 
-- hosts (array of string) - AmazonOpensearchService domain endpoint : port number
-- auth_type (Json object) - Which holds other parameters required for authentication
-    - type (string) - "aws_iam"
-    - aws_access_key_id (string) - AWS access key
-    - aws_secret_access_key (string) - AWS secret access key
-    - region (string, :default => "us-east-1") - region in which the domain is located
-    - if we want to pass other optional parameters like profile, session_token,etc. They needs to be added in auth_type
-- port (string) - AmazonOpensearchService listens on port 443 for HTTPS
-- protocol (string) - The protocol used to connect to AmazonOpensearchService is 'https'
+- `hosts` (array of string): The `AmazonOpensearchService` domain endpoint and port number.
+- `auth_type` (JSON object): The authentication settings.
+    - `type` (string): "aws_iam".
+    - `aws_access_key_id` (string): AWS access key.
+    - `aws_secret_access_key` (string): AWS secret access key.
+    - `region` (string, :default => "us-east-1"): The region in which the domain is located.
+- port (string): AmazonOpensearchService listens on port 443 for `HTTPS`.
+- protocol (string): The protocol used to connect. For `AmazonOpensearchService`, the protocol is `https`.
 
 ### Optional Parameters
-- The credential resolution logic can be described as follows:
-    - User passed aws_access_key_id and aws_secret_access_key in configuration
-    - Environment variables - AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (RECOMMENDED since they are recognized by all the AWS SDKs and CLI except for .NET), or AWS_ACCESS_KEY and AWS_SECRET_KEY (only recognized by Java SDK)
-    - Credential profiles file at the default location (~/.aws/credentials) shared by all AWS SDKs and the AWS CLI
-    - Instance profile credentials delivered through the Amazon EC2 metadata service
-- template (path) - You can set the path to your own template here. If no template is specified, the plugin uses the default template.
-- template_name (string, default => "logstash") - Defines how the template is named inside Opensearch
-- service_name (string, default => "es") - Defines the service name to be used for `aws_iam` authentication.
-- legacy_template (boolean, default => true) - Selects the OpenSearch template API. When `true`, uses legacy templates via the _template API. When `false`, uses composable templates via the _index_template API.
-- default_server_major_version (number) - The OpenSearch server major version to use when it's not available from the OpenSearch root URL. If not set, the plugin throws an exception when the version can't be fetched.
+
+- `template` (path): You can set the path to your own template here. If no template is specified, the plugin uses the default template.
+- `template_name` (string, default => `logstash`): Defines how the template is named inside OpenSearch.
+- `service_name` (string): Defines the service name to be used for `aws_iam` authentication.
+- `legacy_template` (Boolean, default => `true`): Selects the OpenSearch template API. When `true`, uses legacy templates derived from the `_template` API. When `false`, uses the `index_template` API.
+- `default_server_major_version` (number): The OpenSearch server major version to use when it's not available from the OpenSearch root URL. If not set, the plugin throws an exception when the version can't be fetched.
+- `target_bulk_bytes` (number): The maximum number of bytes in the buffer. When the maximum is reached, Logstash will flush the data to OpenSearch. This is useful when the bulk requests are too large for the OpenSearch cluster and the cluster returns a `429` error.
+
+### Credential resolution logic
+
+The following list provides details on the credential resolution logic:
+
+- A user passes `aws_access_key_id` and `aws_secret_access_key` in the configuration.
+- Environment variables, such `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are recommended since they are recognized by all the AWS SDKs and CLIs except for `.NET`. You can also use `AWS_ACCESS_KEY` and `AWS_SECRET_KEY` which are recognized by the Java SDK.
+- The credential profiles file found in the `~/.aws/credentials` directory, is shared by all AWS SDKs and the AWS CLI.
+- Instance profile credentials are delivered through the Amazon EC2 metadata service.
 
 ## Data streams
 
 The OpenSearch output plugin can store both time series datasets (such as logs, events, and metrics) and non-time series data in OpenSearch.
 The data stream is recommended to index time series datasets (such as logs, metrics, and events) into OpenSearch.
 
-To know more about data streams, refer to this [documentation](https://opensearch.org/docs/latest/opensearch/data-streams/).
+To learn more about data streams, see the [data stream documentation](https://opensearch.org/docs/latest/opensearch/data-streams/).
 
-We can ingest data into a data stream through logstash. We need to create the data stream and specify the name of data stream and the `op_type` of `create` in the output configuration. The sample configuration is shown below:
+To ingest data into a data stream through Logstash, create the data stream and specify the name of the data stream and set the `action` setting to `create`, as shown in the following example configuration:
 
 ```yml
 output {