[apm docs consolidation] Copy APM guide pages into Observability guide (

#3496)

* duplicate apm guide pages in observability guide

* update readme

(cherry picked from commit b96cbbb)

README.md

@@ -31,7 +31,7 @@ To build the docs:
 2. Run the `build_docs` script, passing in the path to the `index.asciidoc` and resource paths to other repos that contain source files. For example, to build the Observability Guide and open it in the browser, run:
 
 ```
-../docs/build_docs --doc ./docs/en/observability/index.asciidoc --chunk 1 --resource ../apm-server/docs/guide --resource ../ingest-docs/docs --open
+../docs/build_docs --doc ./docs/en/observability/index.asciidoc --chunk 3 --resource ../apm-server --resource ../ingest-docs/docs --open
 ```
 
 The above command assumes that [elastic/docs](https://github.com/elastic/docs), [elastic/beats](https://github.com/elastic/beats), and [elastic/apm-server](https://github.com/elastic/apm-server) are checked out into the same parent directory.

docs/en/apm-server/anonymous-auth.asciidoc

@@ -30,7 +30,7 @@ You can only enable and configure anonymous authentication if an <<api-key,API k
 <<secret-token,secret token>> is configured. If neither are configured, these settings will be ignored.
 ====
 
-include::{tab-widget-dir}/anonymous-auth-widget.asciidoc[]
+include::{apm-server-dir}/tab-widgets/anonymous-auth-widget.asciidoc[]
 
 [float]
 [[derive-client-ip]]

docs/en/apm-server/api-keys.asciidoc

@@ -26,7 +26,7 @@ make sure <<agent-tls,TLS>> is enabled, then complete these steps:
 [float]
 === Enable API keys
 
-include::{tab-widget-dir}/api-key-widget.asciidoc[]
+include::{apm-server-dir}/tab-widgets/api-key-widget.asciidoc[]
 
 [[create-api-key-user]]
 [float]
@@ -131,7 +131,7 @@ Keys created using this method can only be used for communication with APM Serve
 [float]
 ===== `apikey` subcommands
 
-include::{docdir}/command-reference.asciidoc[tag=apikey-subcommands]
+include::{apm-server-dir}/command-reference.asciidoc[tag=apikey-subcommands]
 
 [[create-api-key-privileges]]
 [float]

docs/en/apm-server/apm-distributed-tracing.asciidoc

@@ -106,7 +106,7 @@ with each agent's API.
 Sending services must add the `traceparent` header to outgoing requests.
 
 --
-include::{tab-widget-dir}/distributed-trace-send-widget.asciidoc[]
+include::{apm-server-dir}/tab-widgets/distributed-trace-send-widget.asciidoc[]
 --
 
 [float]
@@ -117,7 +117,7 @@ Receiving services must parse the incoming `traceparent` header,
 and start a new transaction or span as a child of the received context.
 
 --
-include::{tab-widget-dir}/distributed-trace-receive-widget.asciidoc[]
+include::{apm-server-dir}/tab-widgets/distributed-trace-receive-widget.asciidoc[]
 --
 
 [float]

docs/en/apm-server/common-problems.asciidoc

@@ -16,7 +16,7 @@ This section describes common problems you might encounter when using a Fleet-ma
 
 If no data shows up in {es}, first make sure that your APM components are properly connected.
 
-include::{tab-widget-dir}/no-data-indexed-widget.asciidoc[]
+include::{apm-server-dir}/tab-widgets/no-data-indexed-widget.asciidoc[]
 
 [[data-indexed-no-apm]]
 [float]
@@ -57,7 +57,7 @@ If the `mapping.name.type` is `"text"`, your APM indices were not set up correct
 To fix this problem, install the APM integration by following these steps:
 
 --
-include::{docdir}/getting-started-apm-server.asciidoc[tag=install-apm-integration]
+include::{apm-server-dir}/getting-started-apm-server.asciidoc[tag=install-apm-integration]
 --
 
 This will reinstall the APM index templates and trigger a data stream index rollover.

docs/en/apm-server/configure/outputs/elasticsearch.asciidoc

@@ -471,4 +471,4 @@ See the <<securing-communication-elasticsearch,secure communication with {es}>>
 or <<configuration-ssl,SSL configuration reference>> for more information.
 
 // Elasticsearch security
-include::{docdir}/https.asciidoc[]
+include::{apm-server-dir}/https.asciidoc[]

docs/en/apm-server/configure/outputs/logstash.asciidoc

@@ -338,4 +338,4 @@ The maximum number of seconds to wait before attempting to connect to
 {ls} after a network error. The default is `60s`.
 
 // Logstash security
-include::{docdir}/shared-ssl-logstash-config.asciidoc[]
+include::{apm-server-dir}/shared-ssl-logstash-config.asciidoc[]

docs/en/apm-server/configure/tls.asciidoc

@@ -9,7 +9,7 @@ SSL/TLS is available for:
 Additional information on getting started with SSL/TLS is available in <<securing-apm-server>>.
 
 // :leveloffset: +2
-include::{docdir}/shared-ssl-config.asciidoc[]
+include::{apm-server-dir}/shared-ssl-config.asciidoc[]
 // :leveloffset: -2
 
-include::{docdir}/ssl-input-settings.asciidoc[leveloffset=-1]
+include::{apm-server-dir}/ssl-input-settings.asciidoc[leveloffset=-1]

docs/en/apm-server/getting-started-apm-server.asciidoc

@@ -8,7 +8,13 @@
 TIP: The easiest way to get started with Elastic APM is by using our
 {ess-product}[hosted {es} Service] on {ecloud}.
 The {es} Service is available on AWS, GCP, and Azure.
+ifeval::["{which-guide}" == "observability"]
+See <<traces-get-started,getting started documentation>> to get started in minutes.
+endif::[]
+ifeval::["{which-guide}" == "apm"]
 See <<apm-quick-start>> to get started in minutes.
+endif::[]
+
 
 // TODO: MOVE THIS
 IMPORTANT: Starting in version 8.0.0, {fleet} uses the APM integration to set up and manage APM index templates,
@@ -138,7 +144,7 @@ image::./images/fm-ov.png[APM Server fleet overview]
 Use the decision tree below to help determine which method of configuring and running the APM Server is best for your use case.
 
 [subs=attributes+]
-include::{docdir}/diagrams/apm-decision-tree.asciidoc[APM Server decision tree]
+include::{apm-server-dir}/diagrams/apm-decision-tree.asciidoc[APM Server decision tree]
 
 
 === APM Server binary
@@ -468,10 +474,10 @@ you can start visualizing your data in the {kibana-ref}/xpack-apm.html[{apm-app}
 If you're migrating from Jaeger, see <<jaeger-integration>>.
 
 // Shared APM & YUM
-include::{docdir}/repositories.asciidoc[]
+include::{apm-server-dir}/repositories.asciidoc[]
 
 // Shared docker
-include::{docdir}/shared-docker.asciidoc[]
+include::{apm-server-dir}/shared-docker.asciidoc[]
 
 
 === Fleet-managed APM Server
@@ -504,7 +510,7 @@ include::{obs-repo-dir}/observability/tab-widgets/add-apm-integration/content.as
 An internet connection is required to install the APM integration via the Fleet UI in Kibana.
 
 --
-include::{docdir}/getting-started-apm-server.asciidoc[tag=install-apm-integration-no-internet]
+include::{apm-server-dir}/getting-started-apm-server.asciidoc[tag=install-apm-integration-no-internet]
 --
 ****
 
@@ -529,7 +535,7 @@ This should match the secret token defined when setting up the APM integration.
 TIP: You can edit your APM integration settings if you need to change the APM Server URL
 or secret token to match your APM agents.
 
-include::{tab-widget-dir}/install-agents-widget.asciidoc[]
+include::{apm-server-dir}/tab-widgets/install-agents-widget.asciidoc[]
 
 ==== Step 4: View your data
 

docs/en/apm-server/integrations-index.asciidoc

@@ -3,7 +3,6 @@ include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 
 :apm-integration-docs:
 :obs-repo-dir:           {observability-docs-root}/docs/en
-:tab-widget-dir:         {docdir}/tab-widgets
 
 :github_repo_link: https://github.com/elastic/apm-server/blob/v{version}
 ifeval::["{version}" == "8.0.0"]
@@ -49,6 +48,10 @@ endif::[]
 
 :downloads: https://artifacts.elastic.co/downloads/apm-server
 
+// Temporary attributes
+:which-guide:            apm
+:apm-server-dir:         {observability-docs-root}/docs/en/apm-server
+
 // END OTHER ATTRS
 
 [[apm-user-guide]]
@@ -58,7 +61,7 @@ include::apm-overview.asciidoc[]
 
 include::apm-quick-start.asciidoc[]
 
-include::{docdir}/getting-started-apm-server.asciidoc[]
+include::getting-started-apm-server.asciidoc[]
 
 include::data-model.asciidoc[]
 
@@ -72,7 +75,7 @@ include::manage-storage.asciidoc[]
 
 include::configure/index.asciidoc[leveloffset=+1]
 
-include::{docdir}/setting-up-and-running.asciidoc[]
+include::setting-up-and-running.asciidoc[]
 
 include::secure-comms.asciidoc[]
 
@@ -88,4 +91,6 @@ include::release-notes.asciidoc[leveloffset=+1]
 
 include::known-issues.asciidoc[leveloffset=+1]
 
-include::{docdir}/redirects.asciidoc[]
+include::redirects.asciidoc[]
+
+:which-guide:

docs/en/apm-server/jaeger-integration.asciidoc

@@ -47,7 +47,7 @@ IMPORTANT: There are <<caveats-jaeger,caveats>> to this integration.
 
 The APM integration serves Jaeger gRPC over the same host and port as the Elastic {apm-agent} protocol.
 
-include::{tab-widget-dir}/jaeger-widget.asciidoc[]
+include::{apm-server-dir}/tab-widgets/jaeger-widget.asciidoc[]
 
 [float]
 [[configure-sampling-jaeger]]

docs/en/apm-server/manage-storage.asciidoc

@@ -207,4 +207,4 @@ POST /.ds-*-apm*/_update_by_query?expand_wildcards=all
 
 TIP: Remember to also change the service name in the {apm-agents-ref}/index.html[{apm-agent} configuration].
 
-include::{docdir}/exploring-es-data.asciidoc[leveloffset=+2]
+include::{apm-server-dir}/exploring-es-data.asciidoc[leveloffset=+2]

docs/en/apm-server/monitor-apm-server.asciidoc

@@ -28,4 +28,4 @@ all you have to do is flip a switch and watch the data pour in.
 
 include::./monitor.asciidoc[]
 
-include::{docdir}/monitoring/monitoring-beats.asciidoc[leveloffset=+2]
+include::{apm-server-dir}/monitoring/monitoring-beats.asciidoc[leveloffset=+2]

docs/en/apm-server/otel-metrics.asciidoc

@@ -33,7 +33,7 @@ Use *Discover* to validate that metrics are successfully reported to {kib}.
 . Launch {kib}:
 +
 --
-include::{tab-widget-dir}/open-kibana-widget.asciidoc[]
+include::{apm-server-dir}/tab-widgets/open-kibana-widget.asciidoc[]
 --
 
 . Open the main menu, then click *Discover*.

docs/en/apm-server/secret-token.asciidoc

@@ -24,7 +24,7 @@ as there is no way to prevent them from being publicly exposed.
 NOTE: {ess} and {ece} deployments provision a secret token when the deployment is created.
 The secret token can be found and reset in the {ecloud} console under **Deployments** -- **APM & Fleet**.
 
-include::{tab-widget-dir}/secret-token-widget.asciidoc[]
+include::{apm-server-dir}/tab-widgets/secret-token-widget.asciidoc[]
 
 [[configure-secret-token]]
 [float]

docs/en/apm-server/secure-comms.asciidoc

@@ -15,8 +15,8 @@ process and connecting securely to APM agents and the {stack}.
 include::secure-agent-communication.asciidoc[]
 
 // APM privileges
-include::{docdir}/feature-roles.asciidoc[]
+include::{apm-server-dir}/feature-roles.asciidoc[]
 
 // APM API keys
-include::{docdir}/access-api-keys.asciidoc[]
+include::{apm-server-dir}/access-api-keys.asciidoc[]
 :leveloffset: -1

docs/en/apm-server/setting-up-and-running.asciidoc

@@ -6,8 +6,15 @@
 <titleabbrev>Advanced setup</titleabbrev>
 ++++
 
+ifeval::["{which-guide}" == "observability"]
+Before reading this section, see the <<traces-get-started,getting started documentation>>
+for basic installation and running instructions.
+endif::[]
+
+ifeval::["{which-guide}" == "apm"]
 Before reading this section, see the <<getting-started-apm-server,getting started documentation>>
 for basic installation and running instructions.
+endif::[]
 
 This section includes additional information on how to set up and run APM Server, including:
 
@@ -18,14 +25,14 @@ This section includes additional information on how to set up and run APM Server
 * <<high-availability>>
 * <<running-on-docker>>
 
-include::{docdir}/shared-directory-layout.asciidoc[]
+include::{apm-server-dir}/shared-directory-layout.asciidoc[]
 
-include::{docdir}/keystore.asciidoc[]
+include::{apm-server-dir}/keystore.asciidoc[]
 
-include::{docdir}/command-reference.asciidoc[]
+include::{apm-server-dir}/command-reference.asciidoc[]
 
-include::{docdir}/data-ingestion.asciidoc[]
+include::{apm-server-dir}/data-ingestion.asciidoc[]
 
-include::{docdir}/high-availability.asciidoc[]
+include::{apm-server-dir}/high-availability.asciidoc[]
 
-include::{docdir}/shared-systemd.asciidoc[]
+include::{apm-server-dir}/shared-systemd.asciidoc[]

docs/en/apm-server/shared-directory-layout.asciidoc

@@ -30,5 +30,5 @@ include::{ingest-docs-root}/docs/en/ingest-management/tab-widgets/install-layout
 APM Server uses the following default paths unless you explicitly change them.
 
 --
-include::{tab-widget-dir}/directory-layout-widget.asciidoc[]
+include::{apm-server-dir}/tab-widgets/directory-layout-widget.asciidoc[]
 --

docs/en/apm-server/shared-systemd.asciidoc

@@ -104,5 +104,5 @@ include drop-in unit files. If you need to add a drop-in manually, use
 +systemctl edit {beatname_pkg}.service+.
 
 ifdef::apm-server[]
-include::{docdir}/config-ownership.asciidoc[]
+include::{apm-server-dir}/config-ownership.asciidoc[]
 endif::apm-server[]

docs/en/apm-server/ssl-input-settings.asciidoc

@@ -10,7 +10,7 @@ Most options on this page are supported by all APM Server deployment methods.
 These settings apply to SSL/TLS communication between the APM Server and APM Agents.
 See <<agent-tls>> to learn more.
 
-include::{tab-widget-dir}/tls-widget.asciidoc[]
+include::{apm-server-dir}/tab-widgets/tls-widget.asciidoc[]
 
 [float]
 ==== Enable TLS
@@ -79,7 +79,7 @@ individually configurable in Go, so they are not included in this list.
 | Fleet-managed     | `Cipher suites for TLS connections`
 |====
 
-include::{docdir}/shared-ssl-config.asciidoc[tag=cipher_suites]
+include::{apm-server-dir}/shared-ssl-config.asciidoc[tag=cipher_suites]
 
 [float]
 ==== Curve types for ECDHE based cipher suites

docs/en/apm-server/tls-comms.asciidoc

@@ -32,7 +32,7 @@ location of the output zip archive containing the certificate and the private ke
 
 Enable TLS and configure the APM Server to point to the extracted certificate and key:
 
-include::{tab-widget-dir}/tls-widget.asciidoc[]
+include::{apm-server-dir}/tab-widgets/tls-widget.asciidoc[]
 
 [float]
 [[agent-self-sign-3]]

docs/en/apm-server/troubleshoot-apm.asciidoc

@@ -53,4 +53,4 @@ include::apm-response-codes.asciidoc[]
 
 include::processing-performance.asciidoc[]
 
-include::{docdir}/debugging.asciidoc[]
+include::{apm-server-dir}/debugging.asciidoc[]

docs/en/apm-server/upgrading-to-8.x.asciidoc

@@ -81,10 +81,10 @@ See the {stack-ref}/upgrading-elastic-stack.html[{stack} Installation and Upgrad
 
 . **Install the APM integration via the {fleet} UI**
 +
-include::{docdir}/getting-started-apm-server.asciidoc[tag=why-apm-integration]
+include::{apm-server-dir}/getting-started-apm-server.asciidoc[tag=why-apm-integration]
 +
 --
-include::{docdir}/getting-started-apm-server.asciidoc[tag=install-apm-integration]
+include::{apm-server-dir}/getting-started-apm-server.asciidoc[tag=install-apm-integration]
 --
 
 . **Install the {version} APM Server release**