From 12bf233b502a1d9a5d42a2e3b9fbbefaea5a9c26 Mon Sep 17 00:00:00 2001
From: Carson Ip <carsonip@users.noreply.github.com>
Date: Fri, 12 Apr 2024 11:32:27 +0100
Subject: [PATCH] Add APM data stream rerouting docs (#3730)

Describe APM data stream rerouting, add links to ES reroute processor, apm ingest pipelines and fleet default ingest pipelines.

(cherry picked from commit 1c82b46d4cd29bb4357ddb3626e846b4688d97a8)

# Conflicts:
#	docs/en/observability/apm/ingest-pipelines.asciidoc
---
 .../observability/apm/data-streams.asciidoc   | 28 +++++++++++++++++++
 .../apm/ingest-pipelines.asciidoc             |  5 ++++
 2 files changed, 33 insertions(+)

diff --git a/docs/en/observability/apm/data-streams.asciidoc b/docs/en/observability/apm/data-streams.asciidoc
index cdc7a23296..75d2d93edb 100644
--- a/docs/en/observability/apm/data-streams.asciidoc
+++ b/docs/en/observability/apm/data-streams.asciidoc
@@ -85,6 +85,34 @@ Logs are stored in the following data streams:
 - APM app logging: `logs-apm.app.<service.name>-<namespace>`
 // end::logs-data-streams[]
 
+[discrete]
+[[apm-data-stream-rerouting]]
+=== APM data stream rerouting
+
+APM supports rerouting APM data to user-defined APM data stream names other than the defaults.
+This can be achieved by using a {ref}/reroute-processor.html[`reroute` processor] in ingest pipelines to set the data stream dataset or namespace.
+The benefit of separating APM data streams is that custom retention and security policies can be used.
+
+For example, consider traces that would originally be indexed to `traces-apm-default`. To set the data stream namespace from the trace's `service.environment` and fallback to a static string `"default"`, create an ingest pipeline named `traces-apm@custom` which will be used automatically:
+
+[source, json]
+----
+[
+  {
+    "reroute": {
+      "namespace": [
+        "{{service.environment}}",
+        "default"
+      ]
+    }
+  }
+]
+----
+
+For more about other ingest pipelines called by default, e.g. `traces-apm@custom`, see {fleet-guide}/data-streams.html#data-streams-pipelines[integration data streams ingest pipelines].
+
+For more custom APM ingest pipeline guides, see <<apm-ingest-pipelines,parse data using ingest pipelines>>.
+
 [discrete]
 [[apm-data-streams-next]]
 === What's next?
diff --git a/docs/en/observability/apm/ingest-pipelines.asciidoc b/docs/en/observability/apm/ingest-pipelines.asciidoc
index 05cfcac9d2..57775faf01 100644
--- a/docs/en/observability/apm/ingest-pipelines.asciidoc
+++ b/docs/en/observability/apm/ingest-pipelines.asciidoc
@@ -63,7 +63,12 @@ The process for creating a custom ingest pipeline is as follows:
 
 If you prefer more guidance, see one of these tutorials:
 
+<<<<<<< HEAD
 * <<filters-ingest-pipeline>> — An APM-specific tutorial where you learn how to obfuscate passwords stored in the `http.request.body.original` field.
+=======
+* <<apm-filters-ingest-pipeline>> — Learn how to obfuscate passwords stored in the `http.request.body.original` field.
+* <<apm-data-stream-rerouting>> — Learn how rerouting APM data to user-defined APM data streams.
+>>>>>>> 1c82b46d (Add APM data stream rerouting docs (#3730))
 * {fleet-guide}/data-streams-pipeline-tutorial.html[Transform data with custom ingest pipelines] — A basic Elastic integration tutorial where you learn how to add a custom field to incoming data.
 
 // end::ingest-pipelines[]
\ No newline at end of file