docs: APM Server documentation updates (#4126) (#4180)

docs/configuring.asciidoc

@@ -7,7 +7,7 @@
 <titleabbrev>Configure</titleabbrev>
 ++++
 
-include::{libbeat-dir}/shared-configuring.asciidoc[]
+include::{libbeat-dir}/shared/configuring-intro.asciidoc[]
 
 * <<configuration-process>>
 * <<configuring-output>>
@@ -52,7 +52,7 @@ include::ssl-input-settings.asciidoc[]
 
 See <<securing-apm-server,Securing APM Server>> for more information.
 
-include::./template-config.asciidoc[]
+include::{libbeat-dir}/template-config.asciidoc[]
 
 include::./ilm-reference.asciidoc[]
 

docs/copied-from-beats/docs/shared-template-load.asciidoc → docs/copied-from-beats/docs/howto/load-index-templates.asciidoc

@@ -1,128 +1,95 @@
-//////////////////////////////////////////////////////////////////////////
-//// This content is shared by all Elastic Beats. Make sure you keep the
-//// descriptions here generic enough to work for all Beats that include
-//// this file. When using cross references, make sure that the cross
-//// references resolve correctly for any files that include this one.
-//// Use the appropriate variables defined in the index.asciidoc file to
-//// resolve Beat names: beatname_uc and beatname_lc
-//// Use the following include to pull this content into a doc file:
-//// include::../../libbeat/docs/shared-template-load.asciidoc[]
-//// This content must be embedded underneath a level 3 heading.
-//////////////////////////////////////////////////////////////////////////
+[id="{beatname_lc}-template"]
+== Load the {es} index template
 
-ifndef::no-output-logstash[]
-NOTE: A connection to Elasticsearch is required to load the index template. If
-the output is not Elasticsearch, you must
-<<load-template-manually,load the template manually>>. 
-endif::[]
+{es} uses {ref}/indices-templates.html[index templates] to define:
 
-In Elasticsearch, {ref}/indices-templates.html[index
-templates] are used to define settings and mappings that determine how fields
-should be analyzed.
+* Settings that control the behavior of your indices. The settings include the
+lifecycle policy used to manage indices as they grow and age.
+* Mappings that determine how fields are analyzed. Each mapping sets the
+{ref}/mapping-types.html[{es} datatype] to use for a specific data field.
 
 The recommended index template file for {beatname_uc} is installed by the
 {beatname_uc} packages. If you accept the default configuration in the
 +{beatname_lc}.yml+ config file, {beatname_uc} loads the template automatically
-after successfully connecting to Elasticsearch. If the template already exists,
+after successfully connecting to {es}. If the template already exists,
 it's not overwritten unless you configure {beatname_uc} to do so.
 
-[[load-template-auto]]
-==== Configure template loading
+ifndef::no-output-logstash[]
+NOTE: A connection to {es} is required to load the index template. If
+the output is not {es} (or {ess}), you must
+<<load-template-manually,load the template manually>>.
+endif::[]
+
+This page shows how to change the default template loading behavior to:
 
-By default, {beatname_uc} automatically loads the recommended template file,
-+fields.yml+, if the Elasticsearch output is enabled. If you want to use the
-default index template, no additional configuration is required. Otherwise, you
-can change the defaults in the +{beatname_lc}.yml+ config file
-to:
+* <<load-custom-template>>
+* <<overwrite-template>>
+* <<disable-template-loading>>
+* <<load-template-manually>>
+
+For a full list of template setup options, see <<configuration-template>>.
+
+[float]
+[[load-custom-template]]
+=== Load your own index template
+
+To load your own index template, set the following options:
 
-* **Load a different template**
-+
 [source,yaml]
 -----
 setup.template.name: "your_template_name"
 setup.template.fields: "path/to/fields.yml"
 -----
-+
+
 If the template already exists, it’s not overwritten unless you configure
 {beatname_uc} to do so.
 
-* **Overwrite an existing template**
-+
+[float]
+[[overwrite-template]]
+=== Overwrite an existing index template
+
+To overwrite a template that's already loaded into {es}, set:
+
 [source,yaml]
 -----
 setup.template.overwrite: true
 -----
 
-* **Disable automatic template loading** 
-+
+[float]
+[[disable-template-loading]]
+=== Disable automatic index template loading
+
+You may want to disable automatic template loading if you're using an output
+other than {es} and need to load the template manually. To disable automatic
+template loading, set:
+
 [source,yaml]
 -----
 setup.template.enabled: false
 -----
-+
-If you disable automatic template loading, you need to
-<<load-template-manually,load the template manually>>.
-
-* **Change the index name**
-ifndef::no_ilm[]
-+
-TIP: If you're sending events to a cluster that supports index lifecycle
-management, see <<ilm>> to learn how to change the index name.
-endif::no_ilm[]
-+
-{beatname_uc} uses time series indices, by default, when index lifecycle
-management is disabled or unsupported. The indices are named
-+{beatname_lc}-{version}-yyyy.MM.dd+, where `yyyy.MM.dd` is the date when the
-events were indexed. To use a different name, you set the
-<<index-option-es,`index`>> option in the Elasticsearch output. The value that
-you specify should include the root name of the index plus version and date
-information. You also need to configure the `setup.template.name` and
-`setup.template.pattern` options to match the new name. For example:
-+
-["source","sh",subs="attributes,callouts"]
------
-output.elasticsearch.index: "customname-%{[{beat_version_key}]}-%{+yyyy.MM.dd}"
-setup.template.name: "customname"
-setup.template.pattern: "customname-*"
------
-WARNING: If <<ilm,index lifecycle management>> is enabled (which is typically the default), `setup.template.name` and `setup.template.pattern` are ignored.
-
-ifndef::no_dashboards[]
-+
-If you're using pre-built Kibana dashboards, also set the
-`setup.dashboards.index` option. For example: 
-+
-[source, yaml]
-----
-setup.dashboards.index: "customname-*"
-----
-endif::no_dashboards[]
-
-ifdef::no_dashboards[]
-Remember to change the index name when you load dashboards via the Kibana UI.
-endif::no_dashboards[]
-
-See <<configuration-template>> for the full list of configuration options.
 
+If you disable automatic template loading, you must load the index template
+manually.
 
+[float]
 [[load-template-manually]]
-==== Load the template manually
+=== Load the index template manually
 
-To load the template manually, run the <<setup-command,`setup`>> command. A
-connection to Elasticsearch is required.  If another output is enabled, you need
-to temporarily disable that output and enable Elasticsearch by using the `-E`
-option.
+To load the index template manually, run the <<setup-command,`setup`>> command.
+A connection to {es} is required.  If another output is enabled, you need to
+temporarily disable that output and enable {es} by using the `-E` option.
 ifndef::no-output-logstash[]
 The examples here assume that Logstash output is enabled.
 endif::[]
-You can omit the `-E` flags if Elasticsearch output is already enabled.
-
+You can omit the `-E` flags if {es} output is already enabled.
 
-If you are connecting to a secured Elasticsearch cluster, make sure you've
-configured credentials as described in <<{beatname_lc}-configuration>>.
+ifndef::apm-server[]
+If you are connecting to a secured {es} cluster, make sure you've
+configured credentials as described in the <<{beatname_lc}-installation-configuration>>.
+endif::[]
 
 If the host running {beatname_uc} does not have direct connectivity to
-Elasticsearch, see <<load-template-manually-alternate>>.
+{es}, see <<load-template-manually-alternate>>.
 
 ifndef::win_only[]
 To load the template, use the appropriate command for your system.
@@ -141,7 +108,7 @@ ifdef::no-output-logstash[]
 endif::[]
 
 ifdef::requires-sudo[]
-include::./shared-note-sudo.asciidoc[]
+include::{libbeat-dir}/shared-note-sudo.asciidoc[]
 endif::requires-sudo[]
 
 ifdef::deb_os,rpm_os[]
@@ -204,10 +171,11 @@ PS > .{backslash}{beatname_lc}.exe setup --index-management{disable_logstash} -E
 ----------------------------------------------------------------------
 endif::win_os[]
 
+[float]
 [[force-kibana-new]]
-===== Force Kibana to look at newest documents
+==== Force Kibana to look at newest documents
 
-If you've already used {beatname_uc} to index data into Elasticsearch,
+If you've already used {beatname_uc} to index data into {es},
 the index may contain old documents. After you load the index template,
 you can delete the old documents from +{beatname_lc}-*+ to force Kibana to look
 at the newest documents.
@@ -256,11 +224,12 @@ This command deletes all indices that match the pattern +{beat_default_index_pre
 Before running this command, make sure you want to delete all indices that match
 the pattern.
 
+[float]
 [[load-template-manually-alternate]]
-==== Load the template manually (alternate method)
+=== Load the index template manually (alternate method)
 
 If the host running {beatname_uc} does not have direct connectivity to
-Elasticsearch, you can export the index template to a file, move it to a
+{es}, you can export the index template to a file, move it to a
 machine that does have connectivity, and then install the template manually.
 
 To export the index template, run:

docs/copied-from-beats/docs/monitoring/monitoring-beats.asciidoc

@@ -10,10 +10,10 @@
 
 You can use the {stack} {monitor-features} to gain insight into the health of
 ifndef::apm-server[]
-{beatname_uc} instances running in your environment. 
+{beatname_uc} instances running in your environment.
 endif::[]
 ifdef::apm-server[]
-{beatname_uc}. 
+{beatname_uc}.
 endif::[]
 
 To monitor {beatname_uc}, make sure monitoring is enabled on your {es} cluster,
@@ -23,18 +23,16 @@ of following methods:
 * <<monitoring-internal-collection,Internal collection>> - Internal
 collectors send monitoring data directly to your monitoring cluster.
 ifndef::serverless[]
-* <<monitoring-metricbeat-collection, {metricbeat} collection>> - 
+* <<monitoring-metricbeat-collection, {metricbeat} collection>> -
 {metricbeat} collects monitoring data from your {beatname_uc} instance
 and sends it directly to your monitoring cluster.
 endif::[]
-* <<monitoring-internal-collection-legacy,Legacy collection (deprecated)>> - 
-Legacy collectors send monitoring data to your production cluster.
 
 
 //Commenting out this link temporarily until the general monitoring docs can be
-//updated. 
-//To learn about monitoring in general, see 
-//{ref}/monitor-elasticsearch-cluster.html[Monitor a cluster]. 
+//updated.
+//To learn about monitoring in general, see
+//{ref}/monitor-elasticsearch-cluster.html[Monitor a cluster].
 
 --
 
@@ -43,5 +41,3 @@ include::monitoring-internal-collection.asciidoc[]
 ifndef::serverless[]
 include::monitoring-metricbeat.asciidoc[]
 endif::[]
-
-include::monitoring-internal-collection-legacy.asciidoc[]

docs/copied-from-beats/docs/monitoring/monitoring-internal-collection.asciidoc

@@ -102,10 +102,9 @@ monitoring:
   elasticsearch:
     hosts: ["https://example.com:9200", "https://example2.com:9200"]
     username: ""
-    ssl:
-      ssl.certificate_authorities: ["/etc/pki/root/ca.pem"]
-      ssl.certificate: "/etc/pki/client/cert.pem"
-      ssl.key: "/etc/pki/client/cert.key"
+    ssl.certificate_authorities: ["/etc/pki/root/ca.pem"]
+    ssl.certificate: "/etc/pki/client/cert.pem"
+    ssl.key: "/etc/pki/client/cert.key"
 --------------------
 +
 You must specify the `username` as `""` explicitly so that