From f8f16f3031faaabcb177c59f07b52fb66fb1ac8b Mon Sep 17 00:00:00 2001
From: Colleen McGinnis <colleen.mcginnis@elastic.co>
Date: Wed, 29 Nov 2023 00:57:00 -0600
Subject: [PATCH] docs: Add "Known issues" page (#11608)

(cherry picked from commit 667d5fc77727eeff117c8540a3df70af4d89ef40)
---
 docs/integrations-index.asciidoc |  2 ++
 docs/known-issues.asciidoc       | 48 ++++++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+)
 create mode 100644 docs/known-issues.asciidoc

diff --git a/docs/integrations-index.asciidoc b/docs/integrations-index.asciidoc
index b375bf1c621..9a5596a8ea7 100644
--- a/docs/integrations-index.asciidoc
+++ b/docs/integrations-index.asciidoc
@@ -86,4 +86,6 @@ include::upgrading.asciidoc[]
 
 include::release-notes.asciidoc[leveloffset=+1]
 
+include::known-issues.asciidoc[leveloffset=+1]
+
 include::{docdir}/redirects.asciidoc[]
diff --git a/docs/known-issues.asciidoc b/docs/known-issues.asciidoc
new file mode 100644
index 00000000000..15e798763ac
--- /dev/null
+++ b/docs/known-issues.asciidoc
@@ -0,0 +1,48 @@
+[[known-issues]]
+= Known issues
+
+APM has the following known issues:
+
+*Ingesting new JVM metrics in 8.9 and 8.10 breaks upgrade to 8.11 and stops ingestion* +
+_APM Server versions: 8.11.0, 8.11.1_ +
+_Elastic APM Java Agent versions: 1.39.0+_
+
+// Describe the conditions in which this issue occurs
+If you're using the Elastic APM Java Agent v1.39.0+ to send new JVM metrics to APM Server v8.9.x and v8.10.x,
+// Describe the behavior of the issue
+upgrading to 8.11.0 or 8.11.1 will silently fail and stop ingesting APM metrics.
+// Describe why it happens
+// This happens because...
+
+// Include exact error messages linked to this issue
+// so users searching for the error message end up here.
+After upgrading, you will see the following errors:
+
+* APM Server error logs:
++
+[source,txt]
+----
+failed to index document in 'metrics-apm.internal-default' (fail_processor_exception): Document produced by APM Server v8.11.1, which is newer than the installed APM integration (v8.10.3-preview-1695284222). The APM integration must be upgraded.
+----
+
+* Fleet error on integration package upgrade:
++
+[source,txt]
+----
+Failed installing package [apm] due to error: [ResponseError: mapper_parsing_exception
+	Root causes:
+		mapper_parsing_exception: Field [jvm.memory.non_heap.pool.committed] attempted to shadow a time_series_metric]
+----
+
+// Link to fix?
+A fix for this issue is in progress: https://github.com/elastic/kibana/pull/171712[elastic/kibana#171712].
+
+
+// TEMPLATE
+
+////
+*Brief description* +
+_Versions: XX.XX.XX, YY.YY.YY, ZZ.ZZ.ZZ_
+
+Detailed description.
+////