From 39bf7888ef952ab013699e57272e622850fefacb Mon Sep 17 00:00:00 2001
From: Colleen McGinnis <colleen.mcginnis@elastic.co>
Date: Wed, 4 Sep 2024 13:57:49 -0500
Subject: [PATCH 1/2] add headings to apm known issues doc (#4218)

(cherry picked from commit fc7581cfc208bd224089f3440163553a4c62f85e)

# Conflicts:
#	docs/en/observability/apm/known-issues.asciidoc
---
 .../observability/apm/known-issues.asciidoc   | 120 ++++++++++++++++--
 1 file changed, 107 insertions(+), 13 deletions(-)

diff --git a/docs/en/observability/apm/known-issues.asciidoc b/docs/en/observability/apm/known-issues.asciidoc
index 0b87b2df0f..c442adff53 100644
--- a/docs/en/observability/apm/known-issues.asciidoc
+++ b/docs/en/observability/apm/known-issues.asciidoc
@@ -7,20 +7,105 @@ TEMPLATE
 Note: Add known issues for newer Elastic Stack
 versions to the top of this page
 
-*Brief description* +
+[discrete]
+== Brief description
+
 _Versions: XX.XX.XX, YY.YY.YY, ZZ.ZZ.ZZ_
 
-Detailed description including:
+// Detailed description including:
 
-The conditions in which this issue occurs
-The behavior of the issue
-Why it happens
-If applicable, exact error messages linked to this issue so users searching for the error message end up here
-Link to fix
+// The conditions in which this issue occurs
+// The behavior of the issue
+// Why it happens
+// If applicable, exact error messages linked to this issue so users searching for the error message end up here
+// If applicable, link to fix
 ////
 
+<<<<<<< HEAD
+=======
+[discrete]
+== Upgrading to v8.15.0 may cause APM indices to lose their lifecycle policy
+
+_Elastic Stack versions: 8.15.0_ +
+_Fixed in Elastic Stack version 8.15.1_
+
+// The conditions in which this issue occurs
+The issue only occurs when _upgrading_ the {stack} to 8.15.0.
+The issue does _not_ occur when creating a _new_ cluster using 8.15.0.
+The issue also does not occur if a custom ILM policy is configured using a custom component template.
+
+// Describe why it happens
+In 8.15.0, APM Server switched to use data stream lifecycle to manage data retention
+for APM indices for new deployments as well as for upgraded deployments with default lifecycle
+configurations. Unfortunately, since any data stream created before 8.15.0 does not have a data
+stream lifecycle configuration, such existing data streams become unmanaged for default
+lifecycle configurations.
+
+// How to fix it
+Upgrading to 8.15.1 should fix any new indices created for the data stream. However,
+indices created in version 8.15.0 would remain unmanaged if the default ILM policy is
+used. One of the following approaches can be adopted to fix the unmanaged indices:
+1. Manually delete the indices when they are no longer needed.
+2. Explicitly configure APM data streams with the default data stream lifecycle config.
+Using this approach would migrate all data streams to use data stream lifecycles,
+which should be equivalent to the default ILM policies:
+
+[source,txt]
+----
+PUT _data_stream/traces-apm-*/_lifecycle
+{
+  "data_retention": "10d"
+}
+
+PUT _data_stream/traces-apm.rum*/_lifecycle
+{
+  "data_retention": "90d"
+}
+
+PUT _data_stream/traces-apm.sampled*/_lifecycle
+{
+  "data_retention": "1h"
+}
+
+PUT _data_stream/metrics-apm.*.1m-*/_lifecycle
+{
+  "data_retention": "90d"
+}
+
+PUT _data_stream/metrics-apm.*.10m-*/_lifecycle
+{
+  "data_retention": "180d"
+}
+
+PUT _data_stream/metrics-apm.*.60m-*/_lifecycle
+{
+  "data_retention": "390d"
+}
+
+PUT _data_stream/metrics-apm.internal-*/_lifecycle
+{
+  "data_retention": "90d"
+}
+
+PUT _data_stream/metrics-apm.app.*/_lifecycle
+{
+  "data_retention": "90d"
+}
+
+PUT _data_stream/logs-apm.*/_lifecycle
+{
+  "data_retention": "10d"
+}
+----
+
+// Link to fix if it exists
+This issue is fixed in 8.15.1 (https://github.com/elastic/elasticsearch/pull/112432[elastic/elasticsearch#112432]).
+
+[discrete]
+>>>>>>> fc7581cf (add headings to apm known issues doc (#4218))
 [[broken-apm-anomaly-rule]]
-*Upgrading to v8.13.0 to v8.13.2 breaks APM anomaly rules* +
+== Upgrading to v8.13.0 to v8.13.2 breaks APM anomaly rules
+
 _Elastic Stack versions: 8.13.0, 8.13.1, 8.13.2_ +
 _Fixed in Elastic Stack version 8.13.3_
 
@@ -147,8 +232,10 @@ curl -u "$KIBANA_USER":"$KIBANA_PASSWORD" -XPUT "$KIBANA_URL/api/alerting/rule/0
 Once the PUT request executes successfully, the rule will no longer be broken.
 ====
 
+[discrete]
 [[apm-empty-metricset-values]]
-*Upgrading APM Server to 8.11+ might break event intake from older APM Java agents* +
+== Upgrading APM Server to 8.11+ might break event intake from older APM Java agents
+
 _APM Server versions: >=8.11.0_ +
 _Elastic APM Java agent versions: < 1.43.0_
 
@@ -174,7 +261,9 @@ The fix is to upgrade the Elastic APM Java agent to a version >= 1.43.0.
 Find details in https://github.com/elastic/apm-data/pull/157[elastic/apm-data#157].
 
 
-*traces-apm@custom ingest pipeline applied to certain data streams unintentionally* +
+[discrete]
+== traces-apm@custom ingest pipeline applied to certain data streams unintentionally
+
 _APM Server versions: 8.12.0_ +
 
 // Describe the conditions in which this issue occurs
@@ -194,8 +283,9 @@ If you rely on this unintended behavior in 8.12.0, please rename your pipeline t
 // Link to fix?
 A fix was released in 8.12.1: https://github.com/elastic/kibana/pull/175448[elastic/kibana#175448].
 
+[discrete]
+== Ingesting new JVM metrics in 8.9 and 8.10 breaks upgrade to 8.11 and stops ingestion
 
-*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+_
 
@@ -230,7 +320,9 @@ Failed installing package [apm] due to error: [ResponseError: mapper_parsing_exc
 A fix was released in 8.11.2: https://github.com/elastic/kibana/pull/171712[elastic/kibana#171712].
 
 
-*APM integration package upgrade through Fleet causes excessive data stream rollovers* +
+[discrete]
+== APM integration package upgrade through Fleet causes excessive data stream rollovers
+
 _APM Server versions: \<= 8.12.1 +_
 
 // Describe the conditions in which this issue occurs
@@ -260,7 +352,9 @@ Mappings update for metrics-apm.service_destination.10m-default failed due to Re
 A fix was released in 8.12.2: https://github.com/elastic/apm-server/pull/12219[elastic/apm-server#12219].
 
 
-*Performance regression: APM issues too many small bulk requests for Elasticsearch output* +
+[discrete]
+== Performance regression: APM issues too many small bulk requests for Elasticsearch output
+
 _APM Server versions: >=8.13.0, \<= 8.14.2_ +
 
 // Describe the conditions in which this issue occurs

From b5e7e3439fbf23465d41b9c90ce2c181cf3373be Mon Sep 17 00:00:00 2001
From: Colleen McGinnis <colleen.mcginnis@elastic.co>
Date: Wed, 4 Sep 2024 14:43:44 -0500
Subject: [PATCH 2/2] fix merge conflict

---
 .../observability/apm/known-issues.asciidoc   | 81 -------------------
 1 file changed, 81 deletions(-)

diff --git a/docs/en/observability/apm/known-issues.asciidoc b/docs/en/observability/apm/known-issues.asciidoc
index c442adff53..4c12ea13ce 100644
--- a/docs/en/observability/apm/known-issues.asciidoc
+++ b/docs/en/observability/apm/known-issues.asciidoc
@@ -21,88 +21,7 @@ _Versions: XX.XX.XX, YY.YY.YY, ZZ.ZZ.ZZ_
 // If applicable, link to fix
 ////
 
-<<<<<<< HEAD
-=======
 [discrete]
-== Upgrading to v8.15.0 may cause APM indices to lose their lifecycle policy
-
-_Elastic Stack versions: 8.15.0_ +
-_Fixed in Elastic Stack version 8.15.1_
-
-// The conditions in which this issue occurs
-The issue only occurs when _upgrading_ the {stack} to 8.15.0.
-The issue does _not_ occur when creating a _new_ cluster using 8.15.0.
-The issue also does not occur if a custom ILM policy is configured using a custom component template.
-
-// Describe why it happens
-In 8.15.0, APM Server switched to use data stream lifecycle to manage data retention
-for APM indices for new deployments as well as for upgraded deployments with default lifecycle
-configurations. Unfortunately, since any data stream created before 8.15.0 does not have a data
-stream lifecycle configuration, such existing data streams become unmanaged for default
-lifecycle configurations.
-
-// How to fix it
-Upgrading to 8.15.1 should fix any new indices created for the data stream. However,
-indices created in version 8.15.0 would remain unmanaged if the default ILM policy is
-used. One of the following approaches can be adopted to fix the unmanaged indices:
-1. Manually delete the indices when they are no longer needed.
-2. Explicitly configure APM data streams with the default data stream lifecycle config.
-Using this approach would migrate all data streams to use data stream lifecycles,
-which should be equivalent to the default ILM policies:
-
-[source,txt]
-----
-PUT _data_stream/traces-apm-*/_lifecycle
-{
-  "data_retention": "10d"
-}
-
-PUT _data_stream/traces-apm.rum*/_lifecycle
-{
-  "data_retention": "90d"
-}
-
-PUT _data_stream/traces-apm.sampled*/_lifecycle
-{
-  "data_retention": "1h"
-}
-
-PUT _data_stream/metrics-apm.*.1m-*/_lifecycle
-{
-  "data_retention": "90d"
-}
-
-PUT _data_stream/metrics-apm.*.10m-*/_lifecycle
-{
-  "data_retention": "180d"
-}
-
-PUT _data_stream/metrics-apm.*.60m-*/_lifecycle
-{
-  "data_retention": "390d"
-}
-
-PUT _data_stream/metrics-apm.internal-*/_lifecycle
-{
-  "data_retention": "90d"
-}
-
-PUT _data_stream/metrics-apm.app.*/_lifecycle
-{
-  "data_retention": "90d"
-}
-
-PUT _data_stream/logs-apm.*/_lifecycle
-{
-  "data_retention": "10d"
-}
-----
-
-// Link to fix if it exists
-This issue is fixed in 8.15.1 (https://github.com/elastic/elasticsearch/pull/112432[elastic/elasticsearch#112432]).
-
-[discrete]
->>>>>>> fc7581cf (add headings to apm known issues doc (#4218))
 [[broken-apm-anomaly-rule]]
 == Upgrading to v8.13.0 to v8.13.2 breaks APM anomaly rules