[8.12](backport #3730) Add APM data stream rerouting docs

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 <<ingest-pipelines,parse data using ingest pipelines>>.
+
 [discrete]
 [[apm-data-streams-next]]
 === What's next?

docs/en/observability/apm/ingest-pipelines.asciidoc

@@ -63,7 +63,8 @@ The process for creating a custom ingest pipeline is as follows:
 
 If you prefer more guidance, see one of these tutorials:
 
-* <<filters-ingest-pipeline>> — An APM-specific tutorial where you learn how to obfuscate passwords stored in the `http.request.body.original` field.
+* <<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.
 * {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[]
+// end::ingest-pipelines[]