elastic · karenzone · Apr 29, 2025 · Apr 23, 2025
diff --git a/docs/docset.yml b/docs/docset.yml
@@ -12,6 +12,7 @@ toc:
   - toc: release-notes
   - toc: extend
 subs:
+  version: "9.0.0"
   logstash-ref:   "https://www.elastic.co/guide/en/logstash/current"
   ecloud:   "Elastic Cloud"
   esf:   "Elastic Serverless Forwarder"
@@ -44,3 +45,5 @@ subs:
   stack-version: "9.0.0"
   major-version: "9.x"
   docker-repo: "docker.elastic.co/logstash/logstash"
+  ess-leadin-short:   "Our hosted Elasticsearch Service is available on AWS, GCP, and Azure, and you can try it for free at https://cloud.elastic.co/registration"
+  ess-leadin: "You can run Elasticsearch on your own hardware or use our hosted Elasticsearch Service that is available on AWS, GCP, and Azure. Try the Elasticsearch Service for free: https://cloud.elastic.co/registration."
diff --git a/docs/reference/advanced-pipeline.md b/docs/reference/advanced-pipeline.md
@@ -379,7 +379,7 @@ Notice that the event now contains geographic location information:
 Now that the web logs are broken down into specific fields, you’re ready to get your data into Elasticsearch.
 
 ::::{tip}
-{ess-leadin}
+{{ess-leadin}}
 ::::
 
 

diff --git a/docs/reference/connecting-to-cloud.md b/docs/reference/connecting-to-cloud.md
@@ -12,7 +12,7 @@ Examples:
 * `output {elasticsearch { cloud_id => "<cloud id>" cloud_auth => "<cloud auth>" } }`
 * `output {elasticsearch { cloud_id => "<cloud id>" api_key => "<api key>" } }`
 
-{ess-leadin-short}
+{{ess-leadin-short}}
 
 ## Cloud ID [cloud-id]
 

diff --git a/docs/reference/dashboard-monitoring-with-elastic-agent.md b/docs/reference/dashboard-monitoring-with-elastic-agent.md
@@ -144,6 +144,6 @@ A number of dashboards are included to view {{ls}} as a whole, and dashboards th
 From the list of assets, open the **[Metrics {{ls}}] {{ls}} overview** dashboard to view overall performance. Then follow the navigation panel to further drill down into {{ls}} performance.
 
 % TO DO: Use `:class: screenshot`
-![The {{ls}} Overview dashboard in {{kib}} with various metrics from your monitored {ls}](images/integration-dashboard-overview.png)
+![The {{ls}} Overview dashboard in {{kib}} with various metrics from your monitored {{ls}}](images/integration-dashboard-overview.png)
 
 You can hover over any visualization to adjust its settings, or click the **Edit** button to make changes to the dashboard. To learn more, refer to [Dashboard and visualizations](docs-content://explore-analyze/dashboards.md).
diff --git a/docs/reference/dir-layout.md b/docs/reference/dir-layout.md
@@ -15,12 +15,12 @@ This is very convenient because you don’t have to create any directories to st
 
 | Type | Description | Default Location | Setting |
 | --- | --- | --- | --- |
-| home | Home directory of the Logstash installation. | ``{extract.path}`- Directory created by unpacking the archive` |  |
-| bin | Binary scripts, including `logstash` to start Logstash    and `logstash-plugin` to install plugins | ``{extract.path}/bin`` |  |
-| settings | Configuration files, including `logstash.yml` and `jvm.options` | ``{extract.path}/config`` | ``path.settings`` |
-| logs | Log files | ``{extract.path}/logs`` | ``path.logs`` |
-| plugins | Local, non Ruby-Gem plugin files. Each plugin is contained in a subdirectory. Recommended for development only. | ``{extract.path}/plugins`` | ``path.plugins`` |
-| data | Data files used by logstash and its plugins for any persistence needs. | ``{extract.path}/data`` | ``path.data`` |
+| home | Home directory of the Logstash installation. | `{extract.path}`- Directory created by unpacking the archive |  |
+| bin | Binary scripts, including `logstash` to start Logstash    and `logstash-plugin` to install plugins | `{extract.path}/bin` |  |
+| settings | Configuration files, including `logstash.yml` and `jvm.options` | `{extract.path}/config` | `path.settings` |
+| logs | Log files | `{extract.path}/logs` | `path.logs` |
+| plugins | Local, non Ruby-Gem plugin files. Each plugin is contained in a subdirectory. Recommended for development only. | `{extract.path}/plugins` | `path.plugins` |
+| data | Data files used by logstash and its plugins for any persistence needs. | `{extract.path}/data` | `path.data` |
 
 
 ## Directory Layout of Debian and RPM Packages [deb-layout]
@@ -29,13 +29,13 @@ The Debian package and the RPM package each place config files, logs, and the se
 
 | Type | Description | Default Location | Setting |
 | --- | --- | --- | --- |
-| home | Home directory of the Logstash installation. | ``/usr/share/logstash`` |  |
-| bin | Binary scripts including `logstash` to start Logstash    and `logstash-plugin` to install plugins | ``/usr/share/logstash/bin`` |  |
-| settings | Configuration files, including `logstash.yml` and `jvm.options` | ``/etc/logstash`` | ``path.settings`` |
-| conf | Logstash pipeline configuration files | ``/etc/logstash/conf.d/*.conf`` | `See `/etc/logstash/pipelines.yml`` |
-| logs | Log files | ``/var/log/logstash`` | ``path.logs`` |
-| plugins | Local, non Ruby-Gem plugin files. Each plugin is contained in a subdirectory. Recommended for development only. | ``/usr/share/logstash/plugins`` | ``path.plugins`` |
-| data | Data files used by logstash and its plugins for any persistence needs. | ``/var/lib/logstash`` | ``path.data`` |
+| home | Home directory of the Logstash installation. | `/usr/share/logstash` |  |
+| bin | Binary scripts including `logstash` to start Logstash    and `logstash-plugin` to install plugins | `/usr/share/logstash/bin` |  |
+| settings | Configuration files, including `logstash.yml` and `jvm.options` | `/etc/logstash` | `path.settings` |
+| conf | Logstash pipeline configuration files | `/etc/logstash/conf.d/*.conf` | See `/etc/logstash/pipelines.yml` |
+| logs | Log files | `/var/log/logstash` | `path.logs` |
+| plugins | Local, non Ruby-Gem plugin files. Each plugin is contained in a subdirectory. Recommended for development only. | `/usr/share/logstash/plugins` | `path.plugins` |
+| data | Data files used by logstash and its plugins for any persistence needs. | `/var/lib/logstash` | `path.data` |
 
 
 ## Directory Layout of Docker Images [docker-layout]
@@ -44,12 +44,12 @@ The Docker images are created from the `.tar.gz` packages, and follow a similar
 
 | Type | Description | Default Location | Setting |
 | --- | --- | --- | --- |
-| home | Home directory of the Logstash installation. | ``/usr/share/logstash`` |  |
-| bin | Binary scripts, including `logstash` to start Logstash    and `logstash-plugin` to install plugins | ``/usr/share/logstash/bin`` |  |
-| settings | Configuration files, including `logstash.yml` and `jvm.options` | ``/usr/share/logstash/config`` | ``path.settings`` |
-| conf | Logstash pipeline configuration files | ``/usr/share/logstash/pipeline`` | ``path.config`` |
-| plugins | Local, non Ruby-Gem plugin files. Each plugin is contained in a subdirectory. Recommended for development only. | ``/usr/share/logstash/plugins`` | ``path.plugins`` |
-| data | Data files used by logstash and its plugins for any persistence needs. | ``/usr/share/logstash/data`` | ``path.data`` |
+| home | Home directory of the Logstash installation. | `/usr/share/logstash` |  |
+| bin | Binary scripts, including `logstash` to start Logstash    and `logstash-plugin` to install plugins | `/usr/share/logstash/bin` |  |
+| settings | Configuration files, including `logstash.yml` and `jvm.options` | `/usr/share/logstash/config` | `path.settings` |
+| conf | Logstash pipeline configuration files | `/usr/share/logstash/pipeline` | `path.config` |
+| plugins | Local, non Ruby-Gem plugin files. Each plugin is contained in a subdirectory. Recommended for development only. | `/usr/share/logstash/plugins` | `path.plugins` |
+| data | Data files used by logstash and its plugins for any persistence needs. | `/usr/share/logstash/data` | `path.data` |
 
 ::::{note}
 Logstash Docker containers do not create log files by default. They log to standard output.

diff --git a/docs/reference/first-event.md b/docs/reference/first-event.md
@@ -37,16 +37,16 @@ The location of the `bin` directory varies by platform. See [Directory layout](/
 ::::{admonition} macOS Gatekeeper warnings
 :class: important
 
-Apple’s rollout of stricter notarization requirements affected the notarization of the 9.0.0-beta1 {{ls}} artifacts. If macOS Catalina displays a dialog when you first run {{ls}} that interrupts it, you will need to take an action to allow it to run. To prevent Gatekeeper checks on the {{ls}} files, run the following command on the downloaded `.tar.gz` archive or the directory to which was extracted:
+Apple’s rollout of stricter notarization requirements affected the notarization of {{version}} {{ls}} artifacts. If macOS Catalina displays a dialog when you first run {{ls}} that interrupts it, you will need to take an action to allow it to run. To prevent Gatekeeper checks on the {{ls}} files, run the following command on the downloaded `.tar.gz` archive or the directory to which was extracted:
 
 ```sh
 xattr -d -r com.apple.quarantine <archive-or-directory>
 ```
 
-For example, if the `.tar.gz` file was extracted to the default logstash-9.0.0-beta1 directory, the command is:
+For example, if the `.tar.gz` file was extracted to the default logstash-{{version}} directory, the command is:
 
-```sh
-xattr -d -r com.apple.quarantine logstash-9.0.0-beta1
+```sh subs=true
+xattr -d -r com.apple.quarantine logstash-{{version}}
 ```
 
 Alternatively, you can add a security override if a Gatekeeper popup appears by following the instructions in the *How to open an app that hasn’t been notarized or is from an unidentified developer* section of [Safely open apps on your Mac](https://support.apple.com/en-us/HT202491).

diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -5,7 +5,7 @@ mapped_pages:
   - https://www.elastic.co/guide/en/serverless/current/elasticsearch-ingest-data-through-logstash.html
 ---
 
-# Logstash introduction [introduction]
+# Logstash [introduction]
 
 Logstash is an open source data collection engine with real-time pipelining capabilities.
 Logstash can dynamically unify data from disparate sources and normalize the data into destinations of your choice.

diff --git a/docs/reference/logstash-settings-file.md b/docs/reference/logstash-settings-file.md
@@ -59,7 +59,7 @@ The `logstash.yml` file includes these settings.
 | `config.reload.interval` | How often in seconds Logstash checks the config files for changes. Note that the unit qualifier (`s`) is required. | `3s` |
 | `config.debug` | When set to `true`, shows the fully compiled configuration as a debug log message. You must also set `log.level: debug`.  WARNING: The log message will include any *password* options passed to plugin configs as plaintext, and may result  in plaintext passwords appearing in your logs! | `false` |
 | `config.support_escapes` | When set to `true`, quoted strings will process the following escape sequences: `\n` becomes a literal newline (ASCII 10). `\r` becomes a literal carriage return (ASCII 13). `\t` becomes a literal tab (ASCII 9). `\\` becomes a literal backslash `\`. `\"` becomes a literal double quotation mark. `\'` becomes a literal quotation mark. | `false` |
-| `config.field_reference.escape_style` | Provides a way to reference fields that contain [field reference special characters](https://www.elastic.co/guide/en/logstash/current/field-references-deepdive.html#formal-grammar-escape-sequences) `[` and `]`.<br><br>::::{note} <br>This feature is in **technical preview** and may change in the future.<br>::::<br><br><br>Current options are:<br><br>* `percent`: URI-style `%`+`HH` hexadecimal encoding of UTF-8 bytes (`[` → `%5B`; `]` → `%5D`)<br>* `ampersand`: HTML-style `&#`+`DD`+`;` encoding of decimal Unicode code-points (`[` → `&#91;`; `]` → `&#93;`)<br>* `none`: field names containing special characters *cannot* be referenced.<br> | `none` |
+| `config.field_reference.escape_style` | Provides a way to reference fields that contain [field reference special characters](https://www.elastic.co/guide/en/logstash/current/field-references-deepdive.html#formal-grammar-escape-sequences) `[` and `]`.<br><br>Note: This feature is in **technical preview** and may change in the future.<br><br>Current options are:<br><br>* `percent`: URI-style `%`+`HH` hexadecimal encoding of UTF-8 bytes (`[` → `%5B`; `]` → `%5D`)<br>* `ampersand`: HTML-style `&#`+`DD`+`;` encoding of decimal Unicode code-points (`[` → `&#91;`; `]` → `&#93;`)<br>* `none`: field names containing special characters *cannot* be referenced.<br> | `none` |
 | `queue.type` | The internal queuing model to use for event buffering. Specify `memory` for legacy in-memory based queuing, or `persisted` for disk-based ACKed queueing ([persistent queues](/reference/persistent-queues.md)). | `memory` |
 | `path.queue` | The directory path where the data files will be stored when persistent queues are enabled (`queue.type: persisted`). | `path.data/queue` |
 | `queue.page_capacity` | The size of the page data files used when persistent queues are enabled (`queue.type: persisted`). The queue data consists of append-only data files separated into pages. | 64mb |

diff --git a/docs/reference/running-logstash-command-line.md b/docs/reference/running-logstash-command-line.md
@@ -8,16 +8,16 @@ mapped_pages:
 ::::{admonition} macOS Gatekeeper warnings
 :class: important
 
-Apple’s rollout of stricter notarization requirements affected the notarization of the 9.0.0-beta1 {{ls}} artifacts. If macOS Catalina displays a dialog when you first run {{ls}} that interrupts it, you will need to take an action to allow it to run. To prevent Gatekeeper checks on the {{ls}} files, run the following command on the downloaded `.tar.gz` archive or the directory to which was extracted:
+Apple’s rollout of stricter notarization requirements affected the notarization of the {{version}} {{ls}} artifacts. If macOS Catalina displays a dialog when you first run {{ls}} that interrupts it, you will need to take an action to allow it to run. To prevent Gatekeeper checks on the {{ls}} files, run the following command on the downloaded `.tar.gz` archive or the directory to which was extracted:
 
 ```sh
 xattr -d -r com.apple.quarantine <archive-or-directory>
 ```
 
-For example, if the `.tar.gz` file was extracted to the default logstash-9.0.0-beta1 directory, the command is:
+For example, if the `.tar.gz` file was extracted to the default logstash-{{version}} directory, the command is:
 
-```sh
-xattr -d -r com.apple.quarantine logstash-9.0.0-beta1
+```sh subs=true
+xattr -d -r com.apple.quarantine logstash-{{version}}
 ```
 
 Alternatively, you can add a security override if a Gatekeeper popup appears by following the instructions in the *How to open an app that hasn’t been notarized or is from an unidentified developer* section of [Safely open apps on your Mac](https://support.apple.com/en-us/HT202491).
@@ -116,7 +116,11 @@ Logstash has the following flags. You can use the `--help` flag to display this
 
 
 **`--config.debug`**
-:   Show the fully compiled configuration as a debug log message (you must also have `--log.level=debug` enabled). WARNING: The log message will include any *password* options passed to plugin configs as plaintext, and may result in plaintext passwords appearing in your logs!
+:   Show the fully compiled configuration as a debug log message (you must also have `--log.level=debug` enabled).
+
+    :::{warning}
+    The log message will include any *password* options passed to plugin configs as plaintext, and may result in plaintext passwords appearing in your logs!
+    :::
 
 **`-i, --interactive SHELL`**
 :   Drop to shell instead of running as normal. Valid shells are "irb" and "pry".
@@ -128,7 +132,11 @@ Logstash has the following flags. You can use the `--help` flag to display this
 :   Check configuration for valid syntax and then exit. Note that grok patterns are not checked for correctness with this flag. Logstash can read multiple config files from a directory. If you combine this flag with `--log.level=debug`, Logstash will log the combined config file, annotating each config block with the source file it came from.
 
 **`-r, --config.reload.automatic`**
-:   Monitor configuration changes and reload whenever the configuration is changed. NOTE: Use SIGHUP to manually reload the config. The default is false.
+:   Monitor configuration changes and reload whenever the configuration is changed.
+
+    :::{note}
+    Use SIGHUP to manually reload the config. The default is false.
+    :::
 
 **`--config.reload.interval RELOAD_INTERVAL`**
 :   How frequently to poll the configuration location for changes. The default value is "3s". Note that the unit qualifier (`s`) is required.

diff --git a/docs/reference/running-logstash.md b/docs/reference/running-logstash.md
@@ -9,12 +9,11 @@ Logstash is not started automatically after installation. Starting and stopping
 
 As systemd is now the de-facto init system, here are some common operating systems and versions that use it.  This list is intended to be informative, not exhaustive.
 
-|     |     |     |
-| --- | --- | --- |
-| Distribution | Service System |  |
-| Ubuntu 16.04 and newer | [systemd](#running-logstash-systemd) |  |
-| Debian 8 "jessie" and newer | [systemd](#running-logstash-systemd) |  |
-| CentOS (and RHEL) 7 and newer | [systemd](#running-logstash-systemd) |  |
+| Distribution | Service System |
+| --- | --- |
+| Ubuntu 16.04 and newer | [systemd](#running-logstash-systemd) |
+| Debian 8 "jessie" and newer | [systemd](#running-logstash-systemd) |
+| CentOS (and RHEL) 7 and newer | [systemd](#running-logstash-systemd) |
 
 ## Running Logstash by Using Systemd [running-logstash-systemd]
 

diff --git a/docs/reference/secure-connection.md b/docs/reference/secure-connection.md
@@ -24,7 +24,9 @@ Security is enabled by default on the {{es}} cluster (starting in 8.0). You must
 
 {{ess}} uses certificates signed by standard publicly trusted certificate authorities, and therefore setting a cacert is not necessary.
 
-::::{admonition} Security to {{serverless-full}} $$$serverless$$$
+$$$serverless$$$
+
+::::{admonition} Security to {{serverless-full}}
 :class: note
 
 {{es-serverless}} simplifies safe, secure communication between {{ls}} and {{es}}.
@@ -39,11 +41,12 @@ For more details, check out [Grant access using API keys](#ls-api-keys).
 
 ::::
 
+$$$hosted-ess$$$
 
-::::{admonition} Security to hosted {{ess}} $$$hosted-ess$$$
+::::{admonition} Security to hosted {{ess}}
 :class: note
 
-Our hosted {{ess}} on Elastic Cloud simplifies safe, secure communication between {{ls}} and {{es}}. When you configure the [{{ls}} {{es}} output plugin](logstash-docs-md://lsr/plugins-outputs-elasticsearch.md) to use [`cloud_id`](logstash-docs-md://lsr/plugins-outputs-elasticsearch.md#plugins-outputs-elasticsearch-cloud_id) with either the [`cloud_auth` option](logstash-docs-md://lsr/plugins-outputs-elasticsearch.md#plugins-outputs-elasticsearch-cloud_auth) or the [`api_key` option](logstash-docs-md://lsr/plugins-outputs-elasticsearch.md#plugins-outputs-elasticsearch-api_key), no additional SSL configuration steps are needed. {ess-leadin-short}
+Our hosted {{ess}} on Elastic Cloud simplifies safe, secure communication between {{ls}} and {{es}}. When you configure the [{{ls}} {{es}} output plugin](logstash-docs-md://lsr/plugins-outputs-elasticsearch.md) to use [`cloud_id`](logstash-docs-md://lsr/plugins-outputs-elasticsearch.md#plugins-outputs-elasticsearch-cloud_id) with either the [`cloud_auth` option](logstash-docs-md://lsr/plugins-outputs-elasticsearch.md#plugins-outputs-elasticsearch-cloud_auth) or the [`api_key` option](logstash-docs-md://lsr/plugins-outputs-elasticsearch.md#plugins-outputs-elasticsearch-api_key), no additional SSL configuration steps are needed. {{ess-leadin-short}}
 
 Configuration example:
 
@@ -217,7 +220,7 @@ output {
 
 
 ::::{note}
-Hosted {{ess}} simplifies security. This configuration step is not necessary for hosted Elasticsearch Service on Elastic Cloud. {ess-leadin-short}
+Hosted {{ess}} simplifies security. This configuration step is not necessary for hosted Elasticsearch Service on Elastic Cloud. {{ess-leadin-short}}
 ::::
 
 

diff --git a/docs/reference/serverless-monitoring-with-elastic-agent.md b/docs/reference/serverless-monitoring-with-elastic-agent.md
@@ -65,6 +65,6 @@ For the best experience with the Logstash dashboards, we recommend collecting al
 From the list of assets, open the **[Metrics {{ls}}] {{ls}} overview** dashboard to view overall performance. Then follow the navigation panel to further drill down into {{ls}} performance.
 
 % TO DO: Use `:class: screenshot`
-![The {{ls}} Overview dashboard in {{kib}} with various metrics from your monitored {ls}](images/integration-dashboard-overview.png)
+![The {{ls}} Overview dashboard in {{kib}} with various metrics from your monitored {{ls}}](images/integration-dashboard-overview.png)
 
 You can hover over any visualization to adjust its settings, or click the **Edit** button to make changes to the dashboard. To learn more, refer to [Dashboard and visualizations](docs-content://explore-analyze/dashboards.md).