Doc: Add Elastic Agent collection (#15528) (#15589)

Co-authored-by: Rob Bavey <rob.bavey@elastic.co>
(cherry picked from commit c060c00d7c)

Co-authored-by: Karen Metts <35154725+karenzone@users.noreply.github.com>

docs/index.asciidoc

@@ -19,6 +19,7 @@ include::./include/attributes-lsplugins.asciidoc[]
 :jdk:                   1.8.0
 :lsissue:               https://github.com/elastic/logstash/issues
 :lsplugindocs:          https://www.elastic.co/guide/en/logstash-versioned-plugins/current
+:tab-widget-dir:         {docdir}/static/tab-widgets
 
 
 [[introduction]]
@@ -146,6 +147,8 @@ include::static/deploying.asciidoc[]
 include::static/performance-checklist.asciidoc[]
 
 // Monitoring 
+include::static/monitoring/monitoring-ea-intro.asciidoc[] 
+
 include::static/monitoring/monitoring-overview.asciidoc[]
 
 include::static/monitoring/monitoring.asciidoc[]

docs/static/monitoring/monitoring-confirm.asciidoc

@@ -0,0 +1,19 @@
+[float]
+[[confirm-enrollment]]
+//tag::confirm-enrollment-widget[]
+
+After you have confirmed enrollment and data is coming in,  click **View assets** to access dashboards related to the {ls} integration.
+
+For traditional Stack Monitoring UI, the dashboards marked **[Logs {ls}]** are used to visualize the logs
+produced by your {ls} instances, with those marked **[Metrics {ls}]** for the technical preview metrics
+dashboards.
+These are populated with data only if you selected the **Metrics (Technical Preview)** checkbox.
+
+--
+[role="screenshot"]
+image::images/integration-assets-dashboards.png[Integration assets]
+--
+
+A number of dashboards are included to view {ls} as a whole, and dashboards that allow you to drill-down
+into how {ls} is performing on a node, pipeline and plugin basis.
+//end::confirm-enrollment-widget[]

docs/static/monitoring/monitoring-ea-dashboards.asciidoc

@@ -0,0 +1,117 @@
+[[dashboard-monitoring-with-elastic-agent]]
+=== Collect {ls} monitoring data for dashboards
+[subs="attributes"]
+++++
+<titleabbrev>Collect monitoring data for dashboards</titleabbrev>
+++++
+
+{agent} collects monitoring data from your {ls} instance, sends it directly to your monitoring cluster, and shows the data in {ls} dashboards.
+
+You can enroll {agent} in {fleet-guide}/install-fleet-managed-elastic-agent.html[{fleet}] for management from a central location, or you can run {fleet-guide}/install-standalone-elastic-agent.html[{agent} standalone].
+
+**Prerequisites**
+
+Complete these steps as you prepare to collect and ship monitoring data for dashboards:
+
+[[disable-default-db]]
+.Disable default collection of {ls} monitoring metrics
+[%collapsible]
+====
+include::monitoring-prereq-disable-default.asciidoc[]
+====
+
+[[define-cluster__uuid-db]]
+.Specify the target cluster_uuid (optional)
+[%collapsible]
+====
+include::monitoring-prereq-define-cluster.asciidoc[]
+====
+
+[[create-user-db]]
+.Create a monitoring user (standalone agent only)
+[%collapsible]
+====
+include::monitoring-prereq-create-user.asciidoc[]
+====
+
+[discrete]
+[[install-and-configure-db]]
+=== Install and configure {agent}
+
+Install and configure {agent} to collect {ls} monitoring data for dashboards.
+We'll walk you through the process in these steps:
+
+* <<add-logstash-integration-ead>>
+* <<add-agent-to-fleet-ead>>
+* <<view-assets-ead>>
+* <<view-data-dashboard>>
+
+Check out {fleet-guide}/elastic-agent-installation.html[Installing {agent}] in the _Fleet and Elastic Agent Guide_ for more info.
+
+[discrete]
+[[add-logstash-integration-ead]]
+==== Add the {agent} {ls} integration to monitor host logs and metrics
+
+. Go to the {kib} home page, and click **Add integrations**.
++
+--
+[role="screenshot"]
+image::images/kibana-home.png[{kib} home page]
+--
+
+. In the query bar, search for **{ls}** and select the integration to see more
+details.
+
+. Click **Add {ls}**.
+
+. Configure the integration name and add a description (optional).
+
+. Configure the integration to collect logs. 
+* Make sure that **Logs** is turned on if you want to collect logs from your {ls} instance. Be sure that the required settings are correctly configured.
+* Under **Logs**, modify the log paths to match your {ls} environment.
+
+. Configure the integration to collect metrics.
+* Make sure that **Metrics (Technical Preview)** is turned on, and **Metrics (Stack Monitoring)** is turned off.
+* Under **Metrics (Technical Preview)**, make sure the {ls} URL setting
+points to your {ls} instance URLs. +
+By default, the integration collects {ls}
+monitoring metrics from `https://localhost:9600`. If that host and port number are not
+correct, update the `Logstash URL` setting. If you configured {ls} to use encrypted
+communications and/or a username and password, you must access it via HTTPS, and expand the **Advanced Settings** options, and fill in with the appropriate values for your {ls} instance.
+
+. Click **Save and continue**. +
+This step takes a minute or two to complete. When
+it's done, you'll have an agent policy that contains a system integration policy
+for the configuration you just specified.
+. In the popup, click **Add {agent} to your hosts** to open the **Add agent**
+flyout.
++
+TIP: If you accidentally close the popup, go to **{fleet} > Agents** and click
+**Add agent**.
+
+
+[discrete]
+[[add-agent-to-fleet-ead]]
+
+=== Install and run an {agent} on your machine
+// Include section about installing agents
+include::monitoring-install.asciidoc[tag=install-agent-widget]
+
+[discrete]
+[[view-assets-ead]]
+=== View assets
+// Include section about viewing assets
+include::monitoring-confirm.asciidoc[tag=confirm-enrollment-widget]
+
+[discrete]
+[[view-data-dashboard]]
+=== Monitor {ls} logs and metrics
+
+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.
++
+[role="screenshot"]
+image::images/integration-dashboard-overview.png[The {ls} Overview dashboard in {kib} with various metrics from your monitored {ls}]
+
+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
+{kibana-ref}/dashboard.html[Dashboard and visualizations].

docs/static/monitoring/monitoring-ea-intro.asciidoc

@@ -0,0 +1,28 @@
+[[monitoring-with-ea]]
+== Monitoring {ls} with {agent}
+
+You can use {agent} to collect data about {ls} and ship it to the monitoring
+cluster. 
+When you use {agent} collection, the monitoring agent remains
+active even if the {ls} instance does not. 
+Plus you have the option to manage all of your monitoring agents from a central location in {fleet}.
+
+{agent} gives you a single, unified way to add monitoring for logs, metrics, and other
+types of data to a host. Each agent has a single policy you can update to add
+integrations for new data sources, security protections, and more.
+
+You can use {agent} to collect monitoring data for:
+
+* <<dashboard-monitoring-with-elastic-agent,Dashboards>>. {agent} collects
+monitoring data from your {ls} instance, sends it directly to your monitoring
+cluster, and shows the data in {ls} dashboards.
+{ls} dashboards include an extended range of metrics, including plugin
+drilldowns, and plugin specific dashboards for the dissect filter, the grok filter, and the elasticsearch output.
+* <<monitoring-with-elastic-agent,{stack} monitoring>>. Use the Elastic Stack monitoring features to gain insight into the health of {ls} instances running in your environment.
+
+include::monitoring-ea-dashboards.asciidoc[]
+include::monitoring-ea.asciidoc[]
+
+
+
+

docs/static/monitoring/monitoring-ea.asciidoc

@@ -1,85 +1,118 @@
 [[monitoring-with-elastic-agent]]
-=== Collect {ls} monitoring data with {agent}
+=== Collect {ls} monitoring data for stack monitoring
 [subs="attributes"]
 ++++
-<titleabbrev>{agent} collection</titleabbrev>
+<titleabbrev>Collect monitoring data for stack monitoring</titleabbrev>
 ++++
 
-You can use {agent} to collect data about {ls} and ship it to the monitoring
-cluster. The benefit of {agent} collection is that the monitoring agent remains
-active even if the {ls} instance does not. Plus you can manage all your
-monitoring agents from a central location in {fleet}.
+{agent} collects monitoring data from your {ls} instance and sends it directly to your monitoring cluster.
+With {agent} collection the monitoring agent remains active even if the {ls} instance does not. 
 
-To collect and ship monitoring data:
+You can enroll {agent} in {fleet-guide}/install-fleet-managed-elastic-agent.html[{fleet}] for management 
+from a central location, or you can run {fleet-guide}/install-standalone-elastic-agent.html[{agent} standalone]. 
 
-. <<disable-default-include,Disable default collection of monitoring metrics>>
-. <<define-cluster__uuid-include,Specify the target `cluster_uuid` (optional)>>
-. <<configure-metricbeat,Install and configure {agent} to collect monitoring data>>
+**Prerequisites**
 
-[float]
-[[disable-default-include]]
-//include section about disabling default collection from the metricbeat topic
-include::monitoring-mb.asciidoc[tag=disable-default-collection]
+Complete these steps as you prepare to collect and ship monitoring data for stack monitoring:
 
-[float]
-[[define-cluster__uuid-include]]
-//include section about defining cluster_uuid from the metricbeat topic
-include::monitoring-mb.asciidoc[tag=define-cluster-uuid]
+[[disable-default-include-ea]]
+.Disable default collection of {ls} monitoring metrics
+[%collapsible]
+====
+include::monitoring-prereq-disable-default.asciidoc[]
+====
 
-[float]
-[[configure-elastic-agent]]
-==== Install and configure {agent}
+[[define-cluster__uuid-ea]]
+.Specify the target cluster_uuid (optional)
+[%collapsible]
+====
+include::monitoring-prereq-define-cluster.asciidoc[]
+====
 
-Prerequisites:
+[[set-up-monitoring-ea]]
+.Set up {es} monitoring 
+[%collapsible]
+====
+include::monitoring-prereq-setup-es.asciidoc[]
+====
 
-* Set up {es} monitoring and optionally create a monitoring cluster as described
-in the {ref}/monitoring-production.html[{es} monitoring documentation].
-* Create a user on the production cluster that has the
-`remote_monitoring_collector` {ref}/built-in-roles.html[built-in role].
+[[create-user-ea]]
+.Create a monitoring user (standalone agent only)
+[%collapsible]
+====
+include::monitoring-prereq-create-user.asciidoc[]
+====
 
-To collect {ls} monitoring data, add a {ls} integration to an {agent} and
-deploy it to the host where {ls} is running.
+[discrete]
+[[install-and-configure-mon]]
+=== Install and configure {agent}
 
-. Go to the {kib} home page and click **Add integrations**.
+When you have completed the prerequisites, install and configure {agent} to monitor host logs and metrics.
+We'll walk you through the process in these steps:
+
+* <<add-logstash-integration-ea>>
+* <<add-agent-to-fleet-ea>>
+* <<view-assets>>
+* <<view-data-stack>>
+
+Check out {fleet-guide}/elastic-agent-installation.html[Installing {agent}] in the _Fleet and Elastic Agent Guide_ for more info. 
+
+[discrete]
+[[add-logstash-integration-ea]]
+==== Add the {agent} {ls} integration
+
+. Go to the {kib} home page, and click **Add integrations**.
 +
-NOTE: If you're using a monitoring cluster, use the {kib} instance connected to
-the monitoring cluster.
+--
+[role="screenshot"]
+image::images/kibana-home.png[{kib} home page]
+--
 
-. In the query bar, search for and select the **Logstash** integration for
-{agent}.
-. Read the overview to make sure you understand integration requirements and
-other considerations.
-. Click **Add Logstash**.
-+
-TIP: If you're installing an integration for the first time, you may be prompted
-to install {agent}. Click **Add integration only (skip agent installation)**.
+. In the query bar, search for **{ls}** and select the integration to see more
+details about it.
 
-. Configure the integration name and optionally add a description. Make sure you
-configure all required settings:
-* Under **Collect Logstash application and slowlog logs**, modify the log paths
+. Click **Add {ls}**.
+
+. Configure the integration name and optionally add a description.
+
+. Configure the integration to collect logs.
+* Make sure that **Logs** is turned on if you want to collect logs from your {ls} instance, ensuring that the required settings are correctly configured:
+* Under **Logs**, modify the log paths
 to match your {ls} environment.
-* Under **Collect Logstash node metrics and stats**, make sure the hosts setting
+
+. Configure the integration to collect metrics
+* Make sure that **Metrics (Stack Monitoring)** is turned on, and **Metrics (Technical Preview)** is turned off, if you
+want to collect metrics from your {ls} instance
+* Under **Metrics (Stack Monitoring)**, make sure the hosts setting
 points to your {ls} host URLs. By default, the integration collects {ls}
 monitoring metrics from `localhost:9600`. If that host and port number are not
 correct, update the `hosts` setting. If you configured {ls} to use encrypted
 communications, you must access it via HTTPS. For example, use a `hosts` setting
 like
 `https://localhost:9600`.
+
+. Choose where to add the integration policy. +
+Click **New hosts** to add it to new agent policy or **Existing hosts** to add it to an existing agent policy.
+. In the popup, click **Add {agent} to your hosts** to open the **Add agent**
+flyout.
 +
-**Elastic security.** The Elastic {security-features} are enabled by default. 
-Expand **Advanced options** and enter the username and password of a user that has
-the `remote_monitoring_collector` role.
-. Choose where to add the integration policy. Click **New hosts** to add it to
-new agent policy or **Existing hosts** to add it to an existing agent policy.
-. Click **Save and continue**. This step takes a minute or two to complete. When
-it's done, you'll have an agent policy that contains an integration for
-collecting monitoring data from {kib}.
-. If an {agent} is already assigned to the policy and deployed to the host where
-{kib} is running, you're done. Otherwise, you need to deploy an {agent}. To
-deploy an {agent}:
-.. Go to **{fleet} -> Agents**, then click **Add agent**.
-.. Follow the steps in the **Add agent** flyout to download, install,
-and enroll the {agent}. Make sure you choose the agent policy you created
-earlier.
-. Wait a minute or two until incoming data is confirmed.
-. {kibana-ref}/monitoring-data.html[View the monitoring data in {kib}].
+TIP: If you accidentally close the popup, go to **{fleet} > Agents**, then click
+**Add agent** to access the flyout.
+
+[discrete]
+[[add-agent-to-fleet-ea]]
+==== Install and run an {agent} on your machine
+// Include section about installing agents
+include::monitoring-install.asciidoc[tag=install-agent-widget]
+
+[discrete]
+[[view-assets]]
+=== View assets
+// Include section about viewing assets
+include::monitoring-confirm.asciidoc[tag=confirm-enrollment-widget]
+
+[discrete]
+[[view-data-stack]]
+==== Monitor {ls} logs and metrics (Stack Monitoring)
+
+{kibana-ref}/monitoring-data.html[View the monitoring data in {kib}], and navigate to the <<logstash-monitoring-ui, monitoring UI>>.

docs/static/monitoring/monitoring-install.asciidoc

@@ -0,0 +1,11 @@
+[float]
+[[install-agent]]
+//tag::install-agent-widget[]
+
+The **Add agent** flyout has two options: **Enroll in {fleet}** and
+**Run standalone**. 
+Enrolling agents in {fleet} (default) provides a centralized management tool in {kib},
+reducing management overhead. 
+
+include::{tab-widget-dir}/install-agent-widget.asciidoc[]
+//end::install-agent-widget[]

docs/static/monitoring/monitoring-mb.asciidoc

@@ -20,7 +20,6 @@ Want to use {agent} instead? Refer to <<monitoring-with-elastic-agent>>.
 
 [float]
 [[disable-default]]
-//tag::disable-default-collection[]
 ==== Disable default collection of {ls} monitoring metrics
 
 --
@@ -35,12 +34,10 @@ monitoring.enabled: false
 Remove the `#` at the beginning of the line to enable the setting.
 
 --
-//end::disable-default-collection[]
 
 [float]
 [[define-cluster__uuid]]
-//tag::define-cluster-uuid[]
-==== Define `cluster_uuid` (Optional)
+==== Define `cluster_uuid` (optional)
 To bind the metrics of {ls} to a specific cluster, optionally define the `monitoring.cluster_uuid`
 in the configuration file (logstash.yml):
 
@@ -48,7 +45,6 @@ in the configuration file (logstash.yml):
 ----------------------------------
 monitoring.cluster_uuid: PRODUCTION_ES_CLUSTER_UUID
 ----------------------------------
-//end::define-cluster-uuid[]
 
 [float]
 [[configure-metricbeat]]

docs/static/monitoring/monitoring-overview.asciidoc

@@ -1,26 +1,15 @@
 [role="xpack"]
 [[configuring-logstash]]
-== Monitoring {ls}
+== Monitoring {ls} (legacy)
 
 Use the {stack} {monitor-features} to gain insight into the health of
 {ls} instances running in your environment.
-
 For an introduction to monitoring your Elastic stack, see
 {ref}/monitor-elasticsearch-cluster.html[Monitoring a cluster] in the
 {ref}[Elasticsearch Reference].
+Then, make sure that monitoring is enabled on your {es} cluster. 
 
-[float]
-[[configuring-logstash-xpack]]
-=== Configuring monitoring for {ls}
-
-Make sure that monitoring is enabled on your {es} cluster. Then configure *one* of
-these methods to collect {ls} metrics:
-
-* <<monitoring-with-elastic-agent, {agent} collection>>. {agent} collects
-monitoring data from your {ls} instance and sends it directly to your monitoring
-cluster. The benefit of {agent} collection is that the monitoring agent remains
-active even if the {ls} instance does not. Plus you can mange all your
-monitoring agents from a central location in {fleet}.
+These options for collecting {ls} metrics for stack monitoring have been available for a while:
 
 * <<monitoring-with-metricbeat, {metricbeat} collection>>. Metricbeat collects
 monitoring data from your {ls} instance and sends it directly to your monitoring
@@ -30,7 +19,16 @@ agent remains active even if the {ls} instance does not.
 * <<monitoring-internal-collection-legacy,Legacy collection (deprecated)>>. 
 Legacy collectors send monitoring data to your production cluster.
 
-include::monitoring-ea.asciidoc[]
+
+For more features, dependability, and easier management, consider using: 
+
+* <<monitoring-with-elastic-agent, {agent} collection for Stack Monitoring>>. {agent} collects
+monitoring data from your {ls} instance and sends it directly to your monitoring
+cluster, and shows the data in {ls} Dashboards.
+The benefit of {agent} collection is that the monitoring agent remains
+active even if the {ls} instance does not, you can manage all your
+monitoring agents from a central location in {fleet}. 
+
 include::monitoring-mb.asciidoc[]
 include::monitoring-internal-legacy.asciidoc[]
 include::monitoring-ui.asciidoc[]

docs/static/monitoring/monitoring-prereq-create-user.asciidoc

@@ -0,0 +1,5 @@
+//[[create-user]]
+//=== Create a monitoring user (stack monitoring only)
+
+Create a user on the production cluster that has the
+`remote_monitoring_collector` {ref}/built-in-roles.html[built-in role].

docs/static/monitoring/monitoring-prereq-define-cluster.asciidoc

@@ -0,0 +1,10 @@
+//[[define-cluster__uuid]]
+//==== Define `cluster_uuid` (optional)
+
+To bind the metrics of {ls} to a specific cluster, optionally define the `monitoring.cluster_uuid`
+in the configuration file (logstash.yml):
+
+[source,yaml]
+----------------------------------
+monitoring.cluster_uuid: PRODUCTION_ES_CLUSTER_UUID
+----------------------------------

docs/static/monitoring/monitoring-prereq-disable-default.asciidoc

@@ -0,0 +1,12 @@
+// [[disable-default]]
+// ==== Disable default collection of {ls} monitoring metrics
+
+The `monitoring` setting is in the {ls} configuration file (logstash.yml), but is
+commented out: 
+
+[source,yaml]
+----------------------------------
+monitoring.enabled: false
+----------------------------------
+
+Remove the `#` at the beginning of the line to enable the setting.

docs/static/monitoring/monitoring-prereq-setup-es.asciidoc

@@ -0,0 +1,5 @@
+//[[set-up-monitoring]]
+//=== Set up {es} monitoring (stack monitoring only)
+
+Set up {ref}/monitoring-overview.html[{es} monitoring].
+If you would like to create a dedicated monitoring cluster (optional), check out {ref}/monitoring-production.html[{es} monitoring documentation].

docs/static/tab-widgets/install-agent-widget.asciidoc

@@ -0,0 +1,40 @@
+++++
+<div class="tabs" data-tab-group="ts">
+  <div role="tablist" aria-label="tls">
+    <button role="tab"
+            aria-selected="true"
+            aria-controls="fm-tab-ts"
+            id="fm-ts">
+      Fleet-managed
+    </button>
+    <button role="tab"
+            aria-selected="false"
+            aria-controls="standalone-tab-ts"
+            id="standalone-ts"
+            tabindex="-1">
+      Run standalone
+    </button>
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="fm-tab-ts"
+       aria-labelledby="fm-ts">
+++++
+
+include::install-agent.asciidoc[tag=fleet-managed]
+
+++++
+  </div>
+  <div tabindex="0"
+       role="tabpanel"
+       id="standalone-tab-ts"
+       aria-labelledby="standalone-ts"
+       hidden="">
+++++
+
+include::install-agent.asciidoc[tag=standalone]
+
+++++
+  </div>
+</div>
+++++

docs/static/tab-widgets/install-agent.asciidoc

@@ -0,0 +1,39 @@
+// tag::fleet-managed[]
+. When the **Add Agent flyout** appears, stay on the **Enroll in fleet** tab
++
+--
+[role="screenshot"]
+image::../monitoring/images/integration-agent-add.png[Add agent flyout in {kib}]
+--
+. Skip the **Select enrollment token** step. The enrollment token you need is
+already selected.
++
+NOTE: The enrollment token is specific to the {agent} policy that you just
+created. When you run the command to enroll the agent in {fleet}, you will pass
+in the enrollment token.
+
+. Download, install, and enroll the {agent} on your host by selecting
+your host operating system and following the **Install {agent} on your host**
+step.
+
+It takes about a minute for {agent} to enroll in {fleet}, download the
+configuration specified in the policy you just created, and start collecting
+data.
+
+--
+[role="screenshot"]
+image::../monitoring/images/integration-agent-confirm.png[Agent confirm data]
+--
+// end::fleet-managed[]
+
+// tag::standalone[]
+. When the **Add Agent flyout** appears, navigate to the **Run standalone** tab
++
+--
+[role="screenshot"]
+image::../monitoring/images/integration-agent-add-standalone.png[Add agent flyout in {kib}]
+--
+. Configure the agent. Follow all the instructions in **Install Elastic Agent on your host**
+. After unpacking the binary, replace the `elastic-agent.yml` file with that supplied in the Add Agent flyout on the "Run standalone" tab, replacing the values of `ES_USERNAME` and `ES_PASSWORD` appropriately.
+. Run `sudo ./elastic-agent install`
+// end::standalone[]