From ace2614fad04cfdbe51244c77376bec2a68c612a Mon Sep 17 00:00:00 2001 From: Eric Eastwood Date: Thu, 8 Jan 2026 10:03:15 -0600 Subject: [PATCH] Remove docs on dead legacy metric names (#19341) These metrics were [removed completely from the codebase](https://github.com/element-hq/synapse/blob/444bc56cda05953cb24f95f291d1d2906f3045cc/docs/changelogs/CHANGES-2022.md#synapse-1730-2022-12-06) in Synapse v1.73.0 (2022-12-06). 3-years is plenty enough time :fast_forward: The deprecation/removal is still in our [upgrade notes](https://github.com/element-hq/synapse/blob/444bc56cda05953cb24f95f291d1d2906f3045cc/docs/upgrade.md#deprecation-of-legacy-prometheus-metric-names) which points to a durable versioned link with the info still available: https://element-hq.github.io/synapse/v1.69/metrics-howto.html#renaming-of-metrics--deprecation-of-old-names-in-12 --- changelog.d/19341.doc | 1 + docs/metrics-howto.md | 168 ------------------------------------------ docs/upgrade.md | 4 +- 3 files changed, 3 insertions(+), 170 deletions(-) create mode 100644 changelog.d/19341.doc diff --git a/changelog.d/19341.doc b/changelog.d/19341.doc new file mode 100644 index 0000000000..c3d3281211 --- /dev/null +++ b/changelog.d/19341.doc @@ -0,0 +1 @@ +Remove docs on legacy metric names (no longer in the codebase since 2022-12-06). diff --git a/docs/metrics-howto.md b/docs/metrics-howto.md index eb6b90cec9..ce27428b89 100644 --- a/docs/metrics-howto.md +++ b/docs/metrics-howto.md @@ -145,171 +145,3 @@ Example Prometheus target for Synapse with workers: Labels (`instance`, `job`, `index`) can be defined as anything. The labels are used to group graphs in grafana. - -## Renaming of metrics & deprecation of old names in 1.2 - -Synapse 1.2 updates the Prometheus metrics to match the naming -convention of the upstream `prometheus_client`. The old names are -considered deprecated and will be removed in a future version of -Synapse. -**The old names will be disabled by default in Synapse v1.71.0 and removed -altogether in Synapse v1.73.0.** - -| New Name | Old Name | -| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------- | -| python_gc_objects_collected_total | python_gc_objects_collected | -| python_gc_objects_uncollectable_total | python_gc_objects_uncollectable | -| python_gc_collections_total | python_gc_collections | -| process_cpu_seconds_total | process_cpu_seconds | -| synapse_federation_client_sent_transactions_total | synapse_federation_client_sent_transactions | -| synapse_federation_client_events_processed_total | synapse_federation_client_events_processed | -| synapse_event_processing_loop_count_total | synapse_event_processing_loop_count | -| synapse_event_processing_loop_room_count_total | synapse_event_processing_loop_room_count | -| synapse_util_caches_cache_hits | synapse_util_caches_cache:hits | -| synapse_util_caches_cache_size | synapse_util_caches_cache:size | -| synapse_util_caches_cache_evicted_size | synapse_util_caches_cache:evicted_size | -| synapse_util_caches_cache | synapse_util_caches_cache:total | -| synapse_util_caches_response_cache_size | synapse_util_caches_response_cache:size | -| synapse_util_caches_response_cache_hits | synapse_util_caches_response_cache:hits | -| synapse_util_caches_response_cache_evicted_size | synapse_util_caches_response_cache:evicted_size | -| synapse_util_metrics_block_count_total | synapse_util_metrics_block_count | -| synapse_util_metrics_block_time_seconds_total | synapse_util_metrics_block_time_seconds | -| synapse_util_metrics_block_ru_utime_seconds_total | synapse_util_metrics_block_ru_utime_seconds | -| synapse_util_metrics_block_ru_stime_seconds_total | synapse_util_metrics_block_ru_stime_seconds | -| synapse_util_metrics_block_db_txn_count_total | synapse_util_metrics_block_db_txn_count | -| synapse_util_metrics_block_db_txn_duration_seconds_total | synapse_util_metrics_block_db_txn_duration_seconds | -| synapse_util_metrics_block_db_sched_duration_seconds_total | synapse_util_metrics_block_db_sched_duration_seconds | -| synapse_background_process_start_count_total | synapse_background_process_start_count | -| synapse_background_process_ru_utime_seconds_total | synapse_background_process_ru_utime_seconds | -| synapse_background_process_ru_stime_seconds_total | synapse_background_process_ru_stime_seconds | -| synapse_background_process_db_txn_count_total | synapse_background_process_db_txn_count | -| synapse_background_process_db_txn_duration_seconds_total | synapse_background_process_db_txn_duration_seconds | -| synapse_background_process_db_sched_duration_seconds_total | synapse_background_process_db_sched_duration_seconds | -| synapse_storage_events_persisted_events_total | synapse_storage_events_persisted_events | -| synapse_storage_events_persisted_events_sep_total | synapse_storage_events_persisted_events_sep | -| synapse_storage_events_state_delta_total | synapse_storage_events_state_delta | -| synapse_storage_events_state_delta_single_event_total | synapse_storage_events_state_delta_single_event | -| synapse_storage_events_state_delta_reuse_delta_total | synapse_storage_events_state_delta_reuse_delta | -| synapse_federation_server_received_pdus_total | synapse_federation_server_received_pdus | -| synapse_federation_server_received_edus_total | synapse_federation_server_received_edus | -| synapse_handler_presence_notified_presence_total | synapse_handler_presence_notified_presence | -| synapse_handler_presence_federation_presence_out_total | synapse_handler_presence_federation_presence_out | -| synapse_handler_presence_presence_updates_total | synapse_handler_presence_presence_updates | -| synapse_handler_presence_timers_fired_total | synapse_handler_presence_timers_fired | -| synapse_handler_presence_federation_presence_total | synapse_handler_presence_federation_presence | -| synapse_handler_presence_bump_active_time_total | synapse_handler_presence_bump_active_time | -| synapse_federation_client_sent_edus_total | synapse_federation_client_sent_edus | -| synapse_federation_client_sent_pdu_destinations_count_total | synapse_federation_client_sent_pdu_destinations:count | -| synapse_federation_client_sent_pdu_destinations_total | synapse_federation_client_sent_pdu_destinations:total | -| synapse_handlers_appservice_events_processed_total | synapse_handlers_appservice_events_processed | -| synapse_notifier_notified_events_total | synapse_notifier_notified_events | -| synapse_push_bulk_push_rule_evaluator_push_rules_invalidation_counter_total | synapse_push_bulk_push_rule_evaluator_push_rules_invalidation_counter | -| synapse_push_bulk_push_rule_evaluator_push_rules_state_size_counter_total | synapse_push_bulk_push_rule_evaluator_push_rules_state_size_counter | -| synapse_http_httppusher_http_pushes_processed_total | synapse_http_httppusher_http_pushes_processed | -| synapse_http_httppusher_http_pushes_failed_total | synapse_http_httppusher_http_pushes_failed | -| synapse_http_httppusher_badge_updates_processed_total | synapse_http_httppusher_badge_updates_processed | -| synapse_http_httppusher_badge_updates_failed_total | synapse_http_httppusher_badge_updates_failed | -| synapse_admin_mau_current | synapse_admin_mau:current | -| synapse_admin_mau_max | synapse_admin_mau:max | -| synapse_admin_mau_registered_reserved_users | synapse_admin_mau:registered_reserved_users | - -Removal of deprecated metrics & time based counters becoming histograms in 0.31.0 ---------------------------------------------------------------------------------- - -The duplicated metrics deprecated in Synapse 0.27.0 have been removed. - -All time duration-based metrics have been changed to be seconds. This -affects: - -| msec -> sec metrics | -| -------------------------------------- | -| python_gc_time | -| python_twisted_reactor_tick_time | -| synapse_storage_query_time | -| synapse_storage_schedule_time | -| synapse_storage_transaction_time | - -Several metrics have been changed to be histograms, which sort entries -into buckets and allow better analysis. The following metrics are now -histograms: - -| Altered metrics | -| ------------------------------------------------ | -| python_gc_time | -| python_twisted_reactor_pending_calls | -| python_twisted_reactor_tick_time | -| synapse_http_server_response_time_seconds | -| synapse_storage_query_time | -| synapse_storage_schedule_time | -| synapse_storage_transaction_time | - -Block and response metrics renamed for 0.27.0 ---------------------------------------------- - -Synapse 0.27.0 begins the process of rationalising the duplicate -`*:count` metrics reported for the resource tracking for code blocks and -HTTP requests. - -At the same time, the corresponding `*:total` metrics are being renamed, -as the `:total` suffix no longer makes sense in the absence of a -corresponding `:count` metric. - -To enable a graceful migration path, this release just adds new names -for the metrics being renamed. A future release will remove the old -ones. - -The following table shows the new metrics, and the old metrics which -they are replacing. - -| New name | Old name | -| ------------------------------------------------------------- | ---------------------------------------------------------- | -| synapse_util_metrics_block_count | synapse_util_metrics_block_timer:count | -| synapse_util_metrics_block_count | synapse_util_metrics_block_ru_utime:count | -| synapse_util_metrics_block_count | synapse_util_metrics_block_ru_stime:count | -| synapse_util_metrics_block_count | synapse_util_metrics_block_db_txn_count:count | -| synapse_util_metrics_block_count | synapse_util_metrics_block_db_txn_duration:count | -| synapse_util_metrics_block_time_seconds | synapse_util_metrics_block_timer:total | -| synapse_util_metrics_block_ru_utime_seconds | synapse_util_metrics_block_ru_utime:total | -| synapse_util_metrics_block_ru_stime_seconds | synapse_util_metrics_block_ru_stime:total | -| synapse_util_metrics_block_db_txn_count | synapse_util_metrics_block_db_txn_count:total | -| synapse_util_metrics_block_db_txn_duration_seconds | synapse_util_metrics_block_db_txn_duration:total | -| synapse_http_server_response_count | synapse_http_server_requests | -| synapse_http_server_response_count | synapse_http_server_response_time:count | -| synapse_http_server_response_count | synapse_http_server_response_ru_utime:count | -| synapse_http_server_response_count | synapse_http_server_response_ru_stime:count | -| synapse_http_server_response_count | synapse_http_server_response_db_txn_count:count | -| synapse_http_server_response_count | synapse_http_server_response_db_txn_duration:count | -| synapse_http_server_response_time_seconds | synapse_http_server_response_time:total | -| synapse_http_server_response_ru_utime_seconds | synapse_http_server_response_ru_utime:total | -| synapse_http_server_response_ru_stime_seconds | synapse_http_server_response_ru_stime:total | -| synapse_http_server_response_db_txn_count | synapse_http_server_response_db_txn_count:total | -| synapse_http_server_response_db_txn_duration_seconds | synapse_http_server_response_db_txn_duration:total | - -Standard Metric Names ---------------------- - -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 milliseconds. - -| New name | Old name | -| ---------------------------------------- | --------------------------------- | -| process_cpu_user_seconds_total | process_resource_utime / 1000 | -| process_cpu_system_seconds_total | process_resource_stime / 1000 | -| process_open_fds (no \'type\' label) | process_fds | - -The python-specific counts of garbage collector performance have been -renamed. - -| New name | Old name | -| -------------------------------- | -------------------------- | -| python_gc_time | reactor_gc_time | -| python_gc_unreachable_total | reactor_gc_unreachable | -| python_gc_counts | reactor_gc_counts | - -The twisted-specific reactor metrics have been renamed. - -| New name | Old name | -| -------------------------------------- | ----------------------- | -| python_twisted_reactor_pending_calls | reactor_pending_calls | -| python_twisted_reactor_tick_time | reactor_tick_time | diff --git a/docs/upgrade.md b/docs/upgrade.md index 7c9efaccaf..7eb50d1cf1 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -836,7 +836,7 @@ the names of Prometheus metrics. If you want to test your changes before legacy names are disabled by default, you may specify `enable_legacy_metrics: false` in your homeserver configuration. -A list of affected metrics is available on the [Metrics How-to page](https://element-hq.github.io/synapse/v1.69/metrics-howto.html?highlight=metrics%20deprecated#renaming-of-metrics--deprecation-of-old-names-in-12). +A list of affected metrics is available on the [Metrics How-to page](https://element-hq.github.io/synapse/v1.69/metrics-howto.html#renaming-of-metrics--deprecation-of-old-names-in-12). ## Deprecation of the `generate_short_term_login_token` module API method @@ -2431,7 +2431,7 @@ back to v1.3.1, subject to the following: Some counter metrics have been renamed, with the old names deprecated. See [the metrics -documentation](metrics-howto.md#renaming-of-metrics--deprecation-of-old-names-in-12) +documentation](https://element-hq.github.io/synapse/v1.69/metrics-howto.html#renaming-of-metrics--deprecation-of-old-names-in-12) for details. # Upgrading to v1.1.0