diff --git a/develop/print.html b/develop/print.html
index 6eaa8fc983..120bf5b092 100644
--- a/develop/print.html
+++ b/develop/print.html
@@ -1632,6 +1632,25 @@ change: v1.68 and workers cannot process receipts replicated by v1.69 workers, a
vice versa.</p>
<p>Once all workers are upgraded to v1.69 (or downgraded to v1.68), receipts
replication will resume as normal.</p>
+<h2 id="deprecation-of-legacy-prometheus-metric-names"><a class="header" href="#deprecation-of-legacy-prometheus-metric-names">Deprecation of legacy Prometheus metric names</a></h2>
+<p>In current versions of Synapse, some Prometheus metrics are emitted under two different names,
+with one of the names being older but non-compliant with OpenMetrics and Prometheus conventions
+and one of the names being newer but compliant.</p>
+<p>Synapse v1.71.0 will turn the old metric names off <em>by default</em>.
+For administrators that still rely on them and have not had chance to update their
+uses of the metrics, it's possible to specify <code>enable_legacy_metrics: true</code> in
+the configuration to re-enable them temporarily.</p>
+<p>Synapse v1.73.0 will <strong>remove legacy metric names altogether</strong> and it will no longer
+be possible to re-enable them.</p>
+<p>The Grafana dashboard, Prometheus recording rules and Prometheus Consoles included
+in the <code>contrib</code> directory in the Synapse repository have been updated to no longer
+rely on the legacy names. These can be used on a current version of Synapse
+because current versions of Synapse emit both old and new names.</p>
+<p>You may need to update your alerting rules or any other rules that depend on
+the names of Prometheus metrics.
+If you want to test your changes before legacy names are disabled by default,
+you may specify <code>enable_legacy_metrics: false</code> in your homeserver configuration.</p>
+<p>A list of affected metrics is available on the <a href="https://matrix-org.github.io/synapse/v1.69/metrics-howto.html?highlight=metrics%20deprecated#renaming-of-metrics--deprecation-of-old-names-in-12">Metrics How-to page</a>.</p>
<h1 id="upgrading-to-v1680"><a class="header" href="#upgrading-to-v1680">Upgrading to v1.68.0</a></h1>
<p>Two changes announced in the upgrade notes for v1.67.0 have now landed in v1.68.0.</p>
<h2 id="sqlite-version-requirement"><a class="header" href="#sqlite-version-requirement">SQLite version requirement</a></h2>
@@ -5200,6 +5219,24 @@ Defaults to false.</p>
<pre><code class="language-yaml">enable_metrics: true
</code></pre>
<hr />
+<h3 id="enable_legacy_metrics"><a class="header" href="#enable_legacy_metrics"><code>enable_legacy_metrics</code></a></h3>
+<p>Set to <code>true</code> to publish both legacy and non-legacy Prometheus metric names,
+or to <code>false</code> to only publish non-legacy Prometheus metric names.
+Defaults to <code>true</code>. Has no effect if <code>enable_metrics</code> is <code>false</code>.
+<strong>In Synapse v1.71.0, this will default to <code>false</code> before being removed in Synapse v1.73.0.</strong></p>
+<p>Legacy metric names include:</p>
+<ul>
+<li>metrics containing colons in the name, such as <code>synapse_util_caches_response_cache:hits</code>, because colons are supposed to be reserved for user-defined recording rules;</li>
+<li>counters that don't end with the <code>_total</code> suffix, such as <code>synapse_federation_client_sent_edus</code>, therefore not adhering to the OpenMetrics standard.</li>
+</ul>
+<p>These legacy metric names are unconventional and not compliant with OpenMetrics standards.
+They are included for backwards compatibility.</p>
+<p>Example configuration:</p>
+<pre><code class="language-yaml">enable_legacy_metrics: false
+</code></pre>
+<p>See https://github.com/matrix-org/synapse/issues/11106 for context.</p>
+<p><em>Since v1.67.0.</em></p>
+<h2 id="will-be-removed-in-v1730"><a class="header" href="#will-be-removed-in-v1730"><strong>Will be removed in v1.73.0.</strong></a></h2>
<h3 id="sentry"><a class="header" href="#sentry"><code>sentry</code></a></h3>
<p>Use this option to enable sentry integration. Provide the DSN assigned to you by sentry
with the <code>dsn</code> setting.</p>
@@ -13742,7 +13779,9 @@ The labels are used to group graphs in grafana.</p>
<p>Synapse 1.2 updates the Prometheus metrics to match the naming
convention of the upstream <code>prometheus_client</code>. The old names are
considered deprecated and will be removed in a future version of
-Synapse.</p>
+Synapse.
+<strong>The old names will be disabled by default in Synapse v1.71.0 and removed
+altogether in Synapse v1.73.0.</strong></p>
<table><thead><tr><th>New Name</th><th>Old Name</th></tr></thead><tbody>
<tr><td>python_gc_objects_collected_total</td><td>python_gc_objects_collected</td></tr>
<tr><td>python_gc_objects_uncollectable_total</td><td>python_gc_objects_uncollectable</td></tr>
@@ -13752,6 +13791,13 @@ Synapse.</p>
<tr><td>synapse_federation_client_events_processed_total</td><td>synapse_federation_client_events_processed</td></tr>
<tr><td>synapse_event_processing_loop_count_total</td><td>synapse_event_processing_loop_count</td></tr>
<tr><td>synapse_event_processing_loop_room_count_total</td><td>synapse_event_processing_loop_room_count</td></tr>
+<tr><td>synapse_util_caches_cache_hits</td><td>synapse_util_caches_cache:hits</td></tr>
+<tr><td>synapse_util_caches_cache_size</td><td>synapse_util_caches_cache:size</td></tr>
+<tr><td>synapse_util_caches_cache_evicted_size</td><td>synapse_util_caches_cache:evicted_size</td></tr>
+<tr><td>synapse_util_caches_cache</td><td>synapse_util_caches_cache:total</td></tr>
+<tr><td>synapse_util_caches_response_cache_size</td><td>synapse_util_caches_response_cache:size</td></tr>
+<tr><td>synapse_util_caches_response_cache_hits</td><td>synapse_util_caches_response_cache:hits</td></tr>
+<tr><td>synapse_util_caches_response_cache_evicted_size</td><td>synapse_util_caches_response_cache:evicted_size</td></tr>
<tr><td>synapse_util_metrics_block_count_total</td><td>synapse_util_metrics_block_count</td></tr>
<tr><td>synapse_util_metrics_block_time_seconds_total</td><td>synapse_util_metrics_block_time_seconds</td></tr>
<tr><td>synapse_util_metrics_block_ru_utime_seconds_total</td><td>synapse_util_metrics_block_ru_utime_seconds</td></tr>
@@ -13851,7 +13897,7 @@ they are replacing.</p>
<h2 id="standard-metric-names"><a class="header" href="#standard-metric-names">Standard Metric Names</a></h2>
<p>As of synapse version 0.18.2, the format of the process-wide metrics has
been changed to fit prometheus standard naming conventions. Additionally
-the units have been changed to seconds, from miliseconds.</p>
+the units have been changed to seconds, from milliseconds.</p>
<table><thead><tr><th>New name</th><th>Old name</th></tr></thead><tbody>
<tr><td>process_cpu_user_seconds_total</td><td>process_resource_utime / 1000</td></tr>
<tr><td>process_cpu_system_seconds_total</td><td>process_resource_stime / 1000</td></tr>
|
