diff --git a/docs/reference/data-streams/logs.asciidoc b/docs/reference/data-streams/logs.asciidoc
index 7058cfe51496f..381bc8bb91809 100644
--- a/docs/reference/data-streams/logs.asciidoc
+++ b/docs/reference/data-streams/logs.asciidoc
@@ -112,7 +112,9 @@ IMPORTANT: On existing data streams, `logsdb` mode is applied on <<data-streams-
 [[logsdb-sort-routing]]
 ==== Optimized routing on sort fields
 
-To reduce the storage footprint of `logsdb` indexes, you can enable routing optimizations. A routing optimization uses the fields in the sort configuration (except for `@timestamp`) to route documents to shards. 
+If you have the required [subscription](https://www.elastic.co/subscriptions), you can enable routing optimizations
+to reduce the storage footprint of `logsdb` indexes. A routing optimization uses the fields in the sort configuration 
+(except for `@timestamp`) to route documents to shards. 
 
 In benchmarks,
 routing optimizations reduced storage requirements by 20% compared to the default `logsdb` configuration, with a negligible penalty to ingestion
diff --git a/docs/reference/troubleshooting.asciidoc b/docs/reference/troubleshooting.asciidoc
index 75cd0c1be49fc..bd066cd56e1d3 100644
--- a/docs/reference/troubleshooting.asciidoc
+++ b/docs/reference/troubleshooting.asciidoc
@@ -25,6 +25,7 @@ If you're using Elastic Cloud Hosted, then you can use AutoOps to monitor your c
 * <<allow-all-cluster-allocation,Allow Elasticsearch to allocate the data in the system>>
 * <<allow-all-index-allocation,Allow Elasticsearch to allocate the index>>
 * <<troubleshoot-migrate-to-tiers,Indices mix index allocation filters with data tiers node roles to move through data tiers>>
+* <<troubleshoot-migrate-source-mode,Configuring source mode in mappings is deprecated and replaced by an index setting>>
 * <<increase-tier-capacity,Not enough nodes to allocate all shard replicas>>
 * <<increase-shard-limit,Total number of shards for an index on a single node exceeded>>
 * <<increase-cluster-shard-limit,Total number of shards per node has been reached>>
@@ -109,6 +110,8 @@ include::troubleshooting/data/increase-shard-limit.asciidoc[]
 
 include::troubleshooting/data/increase-cluster-shard-limit.asciidoc[]
 
+include::troubleshooting/data/source-mode-setting.asciidoc[]
+
 include::troubleshooting/corruption-issues.asciidoc[]
 
 include::troubleshooting/disk/fix-data-node-out-of-disk.asciidoc[]
diff --git a/docs/reference/troubleshooting/data/source-mode-setting.asciidoc b/docs/reference/troubleshooting/data/source-mode-setting.asciidoc
new file mode 100644
index 0000000000000..0ab6327120436
--- /dev/null
+++ b/docs/reference/troubleshooting/data/source-mode-setting.asciidoc
@@ -0,0 +1,49 @@
+[[troubleshoot-migrate-source-mode]]
+== Configuring source mode in mappings is deprecated and replaced by an index setting
+
+Index <<mapping-source-field,source>> mode was previously configured in mappings as follows:
+
+[source,js]
+----
+"mappings": {
+    "source": {
+        "mode": "synthetic"
+    },
+    "foo": {
+        "type": "keyword"
+    },
+    "bar": {
+        "type": "keyword"
+    }
+}
+----
+// NOTCONSOLE
+
+Starting with version 8.18, this method for configuring the source mode is considered
+deprecated and replaced by index setting `index.mapping.source.mode` that accepts the
+same values: `stored`, `synthetic` and `disabled`. The index setting can be
+used as follows:
+
+[source,js]
+----
+"settings": {
+    "index.mapping.source.mode": "synthetic"
+}
+"mappings": {
+    "foo": {
+        "type": "keyword"
+    },
+    "bar": {
+        "type": "keyword"
+    }
+}
+----
+// NOTCONSOLE
+
+Existing indexes using the deprecated method for configuring the source mode are not
+affected, but creating new indexes raises warnings and will not be supported in a future
+release. This can be an issue for data streams and other indexes that get regularly
+generated using component templates. To avoid these problems, identify all affected
+component templates, as shown in the <<migration-api-deprecation,deprecation info API>>,
+and update them to use setting `index.mapping.source.mode` instead of
+`mappings.source.mode`, according to the examples above.