[do not merge] Move APM guide pages into Observability guide

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/observability/apm.asciidoc

@@ -1,12 +1,106 @@
 [[apm]]
 = Application performance monitoring (APM)
 
+: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"]
+:github_repo_link: https://github.com/elastic/apm-server/blob/main
+endif::[]
+
+
+// OTHER ATTRS
+// TODO: Check that these are still relevant
+:version: {apm_server_version}
+:beatname_lc: apm-server
+:beatname_uc: APM Server
+:beatname_pkg: {beatname_lc}
+:beat_kib_app: APM app
+:beat_monitoring_user: apm_system
+:beat_monitoring_user_version: 6.5.0
+:beat_monitoring_version: 6.5
+:beat_default_index_prefix: apm
+:access_role: {beat_default_index_prefix}_user
+:beat_version_key: observer.version
+:dockerimage: docker.elastic.co/apm/{beatname_lc}:{version}
+:dockergithub: https://github.com/elastic/apm-server-docker/tree/{doc-branch}
+:dockerconfig: https://raw.githubusercontent.com/elastic/apm-server/{doc-branch}/apm-server.docker.yml
+:discuss_forum: apm
+:github_repo_name: apm-server
+:sample_date_0: 2019.10.20
+:sample_date_1: 2019.10.21
+:sample_date_2: 2019.10.22
+:repo: apm-server
+:no_kibana:
+:no_ilm:
+:no-pipeline:
+:no-processors:
+:no-indices-rules:
+:no_dashboards:
+:apm-server:
+:deb_os:
+:rpm_os:
+:mac_os:
+:docker_platform:
+:win_os:
+:linux_os:
+
+:downloads: https://artifacts.elastic.co/downloads/apm-server
+
 Elastic APM is an application performance monitoring system built on the {stack}.
 It allows you to monitor software services and applications in real time, by
 collecting detailed performance information on response time for incoming requests,
 database queries, calls to caches, external HTTP requests, and more.
+This makes it easy to pinpoint and fix performance problems quickly.
 
 [role="screenshot"]
 image::images/apm-app-landing.png[{apm-app} in {kib}]
 
-To learn more, see {apm-guide-ref}/index.html[APM Overview].
+Elastic APM also automatically collects unhandled errors and exceptions.
+Errors are grouped based primarily on the stack trace,
+so you can identify new errors as they appear and keep an eye on how many times specific errors happen.
+
+Metrics are another vital source of information when debugging production systems.
+Elastic APM agents automatically pick up basic host-level metrics and agent-specific metrics,
+like JVM metrics in the Java Agent, and Go runtime metrics in the Go Agent.
+
+[float]
+=== Give Elastic APM a try
+
+Use <<traces-get-started,Get started with application traces and APM>> to quickly spin up an APM deployment.
+Want to host everything yourself instead? See <<getting-started-apm-server>>.
+
+include::apm/getting-started-apm-server.asciidoc[]
+
+include::apm/data-model.asciidoc[]
+
+include::apm/features.asciidoc[]
+
+include::apm/how-to.asciidoc[]
+
+include::apm/open-telemetry.asciidoc[]
+
+include::apm/manage-storage.asciidoc[]
+
+include::apm/configure/index.asciidoc[leveloffset=+1]
+
+include::apm/setting-up-and-running.asciidoc[]
+
+include::apm/secure-comms.asciidoc[]
+
+include::apm/monitor-apm-server.asciidoc[]
+
+include::apm/api.asciidoc[]
+
+include::apm/troubleshoot-apm.asciidoc[]
+
+include::apm/upgrading.asciidoc[]
+
+include::apm/release-notes.asciidoc[leveloffset=+1]
+
+include::apm/known-issues.asciidoc[leveloffset=+1]
+
+// include::apm/redirects.asciidoc[]
+

docs/en/observability/apm/access-api-keys.asciidoc

@@ -0,0 +1,173 @@
+[role="xpack"]
+[[beats-api-keys]]
+=== Grant access using API keys
+
+Instead of using usernames and passwords, you can use API keys to grant
+access to {es} resources. You can set API keys to expire at a certain time,
+and you can explicitly invalidate them. Any user with the `manage_api_key`
+or `manage_own_api_key` cluster privilege can create API keys.
+
+{beatname_uc} instances typically send both collected data and monitoring
+information to {es}. If you are sending both to the same cluster, you can use the same
+API key. For different clusters, you need to use an API key per cluster.
+
+NOTE: For security reasons, we recommend using a unique API key per {beatname_uc} instance.
+You can create as many API keys per user as necessary.
+
+[float]
+[[beats-api-key-publish]]
+==== Create an API key for writing events
+
+In {kib}, navigate to **{stack-manage-app}** > **API keys** and click **Create API key**.
+
+[role="screenshot"]
+image::images/server-api-key-create.png[API key creation]
+
+Enter a name for your API key and select **Restrict privileges**.
+In the role descriptors box, assign the appropriate privileges to the new API key. For example:
+
+[source,json,subs="attributes,callouts"]
+----
+{
+    "{beat_default_index_prefix}_writer": {
+        "index": [
+            {
+                "names": ["{beat_default_index_prefix}-*"],
+                "privileges": ["create_index", "create_doc"]
+            }
+        ]
+    },
+    "{beat_default_index_prefix}_sourcemap": {
+        "index": [
+            {
+                "names": [".apm-source-map"],
+                "privileges": ["read"]
+            }
+        ]
+    },
+    "{beat_default_index_prefix}_agentcfg": {
+        "index": [
+            {
+                "names": [".apm-agent-configuration"],
+                "privileges": ["read"]
+            }
+        ]
+    }
+}
+----
+
+NOTE: This example only provides privileges for **writing data**.
+See <<feature-roles>> for additional privileges and information.
+
+To set an expiration date for the API key, select **Expire after time**
+and input the lifetime of the API key in days.
+
+Click **Create API key**. In the dropdown, switch to **{beats}** and copy the API key.
+
+You can now use this API key in your +{beatname_lc}.yml+ configuration file:
+
+["source","yml",subs="attributes"]
+--------------------
+output.elasticsearch:
+  api_key: TiNAGG4BaaMdaH1tRfuU:KnR6yE41RrSowb0kQ0HWoA <1>
+--------------------
+<1> Format is `id:api_key` (as shown in the {beats} dropdown)
+
+[float]
+[[beats-api-key-monitor]]
+==== Create an API key for monitoring
+
+In {kib}, navigate to **{stack-manage-app}** > **API keys** and click **Create API key**.
+
+[role="screenshot"]
+image::images/server-api-key-create.png[API key creation]
+
+Enter a name for your API key and select **Restrict privileges**.
+In the role descriptors box, assign the appropriate privileges to the new API key.
+For example:
+
+[source,json,subs="attributes,callouts"]
+----
+{
+    "{beat_default_index_prefix}_monitoring": {
+        "index": [
+            {
+                "names": [".monitoring-beats-*"],
+                "privileges": ["create_index", "create_doc"]
+            }
+      ]
+    }
+}
+----
+
+NOTE: This example only provides privileges for **publishing monitoring data**.
+See <<feature-roles>> for additional privileges and information.
+
+To set an expiration date for the API key, select **Expire after time**
+and input the lifetime of the API key in days.
+
+Click **Create API key**. In the dropdown, switch to **{beats}** and copy the API key.
+
+You can now use this API key in your +{beatname_lc}.yml+ configuration file like this:
+
+["source","yml",subs="attributes"]
+--------------------
+monitoring.elasticsearch:
+  api_key: TiNAGG4BaaMdaH1tRfuU:KnR6yE41RrSowb0kQ0HWoA <1>
+--------------------
+<1> Format is `id:api_key` (as shown in the {beats} dropdown)
+
+[float]
+[[beats-api-key-es]]
+==== Create an API key with {es} APIs
+
+You can also use {es}'s {ref}/security-api-create-api-key.html[Create API key API] to create a new API key.
+For example:
+
+[source,console,subs="attributes,callouts"]
+------------------------------------------------------------
+POST /_security/api_key
+{
+  "name": "{beat_default_index_prefix}_host001", <1>
+  "role_descriptors": {
+    "{beat_default_index_prefix}_writer": { <2>
+      "index": [
+        {
+          "names": ["{beat_default_index_prefix}-*"],
+          "privileges": ["create_index", "create_doc"]
+        }
+      ]
+    },
+    "{beat_default_index_prefix}_sourcemap": {
+      "index": [
+        {
+          "names": [".apm-source-map"],
+          "privileges": ["read"]
+        }
+      ]
+    },
+    "{beat_default_index_prefix}_agentcfg": {
+      "index": [
+        {
+          "names": [".apm-agent-configuration"],
+          "privileges": ["read"]
+        }
+      ]
+    }
+  }
+}
+------------------------------------------------------------
+<1> Name of the API key
+<2> Granted privileges, see <<feature-roles>>
+
+See the {ref}/security-api-create-api-key.html[Create API key] reference for more information.
+
+[[learn-more-api-keys]]
+[float]
+==== Learn more about API keys
+
+See the {es} API key documentation for more information:
+
+* {ref}/security-api-create-api-key.html[Create API key]
+* {ref}/security-api-get-api-key.html[Get API key information]
+* {ref}/security-api-invalidate-api-key.html[Invalidate API key]

docs/en/observability/apm/agent-server-compatibility.asciidoc

@@ -0,0 +1,51 @@
+[[agent-server-compatibility]]
+=== {apm-agent} compatibility
+
+The chart below outlines the compatibility between different versions of Elastic APM agents and extensions with the APM integration.
+
+[options="header"]
+|====
+|Language |{apm-agent} version |APM integration version
+// APM AWS Lambda extension
+.1+|**APM AWS Lambda extension**
+|`1.x` |≥ `8.2`
+
+// Go
+.2+|**Go agent**
+|`1.x` |≥ `6.5`
+|`2.x` |≥ `6.5`
+
+// iOS
+.1+|**iOS agent**
+|`0.x` |≥ `7.14`
+
+// Java
+.1+|**Java agent**
+|`1.x`|≥ `6.5`
+
+// .NET
+.1+|**.NET agent**
+|`1.x` |≥ `6.5`
+
+// Node
+.1+|**Node.js agent**
+|`3.x` |≥ `6.6`
+
+// PHP
+.1+|**PHP agent**
+|`1.x` |≥ `7.0`
+
+// Python
+.1+|**Python agent**
+|`6.x` |≥ `6.6`
+
+// Ruby
+.2+|**Ruby agent**
+|`3.x` |≥ `6.5`
+|`4.x` |≥ `6.5`
+
+// RUM
+.2+|**JavaScript RUM agent**
+|`4.x` |≥ `6.5`
+|`5.x` |≥ `7.0`
+|====