Clean up config settings for stats

changelog.d/9604.doc

@@ -0,0 +1 @@
+Clarify the sample configuration for `stats` settings.

changelog.d/9604.misc

@@ -0,0 +1 @@
+Remove unused `stats.retention` setting, and emit a warning if stats are disabled.

docs/sample_config.yaml

@@ -2645,19 +2645,20 @@ user_directory:
 
 
 
-# Local statistics collection. Used in populating the room directory.
+# Settings for local room and user statistics collection. See
+# docs/room_and_user_statistics.md.
 #
-# 'bucket_size' controls how large each statistics timeslice is. It can
-# be defined in a human readable short form -- e.g. "1d", "1y".
-#
-# 'retention' controls how long historical statistics will be kept for.
-# It can be defined in a human readable short form -- e.g. "1d", "1y".
-#
-#
-#stats:
-# enabled: true
-# bucket_size: 1d
-# retention: 1y
+stats:
+ # Uncomment the following to disable room and user statistics. Note that doing
+ # so may cause certain features (such as the room directory) not to work
+ # correctly.
+ #
+ #enabled: false
+
+ # The size of each timeslice in the room_stats_historical and
+ # user_stats_historical tables, as a time period. Defaults to "1d".
+ #
+ #bucket_size: 1h
 
 
 # Server Notices room configuration

synapse/config/stats.py

@@ -13,10 +13,22 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import sys
+import logging
 
 from ._base import Config
 
+ROOM_STATS_DISABLED_WARN = """\
+WARNING: room/user statistics have been disabled via the stats.enabled
+configuration setting. This means that certain features (such as the room
+directory) will not operate correctly. Future versions of Synapse may ignore
+this setting.
+
+To fix this warning, remove the stats.enabled setting from your configuration
+file.
+--------------------------------------------------------------------------------"""
+
+logger = logging.getLogger(__name__)
+
 
 class StatsConfig(Config):
  """Stats Configuration
@@ -28,30 +40,29 @@ class StatsConfig(Config):
  def read_config(self, config, **kwargs):
  self.stats_enabled = True
  self.stats_bucket_size = 86400 * 1000
- self.stats_retention = sys.maxsize
  stats_config = config.get("stats", None)
  if stats_config:
  self.stats_enabled = stats_config.get("enabled", self.stats_enabled)
  self.stats_bucket_size = self.parse_duration(
  stats_config.get("bucket_size", "1d")
  )
- self.stats_retention = self.parse_duration(
- stats_config.get("retention", "%ds" % (sys.maxsize,))
- )
+ if not self.stats_enabled:
+ logger.warning(ROOM_STATS_DISABLED_WARN)
 
  def generate_config_section(self, config_dir_path, server_name, **kwargs):
  return """
- # Local statistics collection. Used in populating the room directory.
+ # Settings for local room and user statistics collection. See
+ # docs/room_and_user_statistics.md.
  #
- # 'bucket_size' controls how large each statistics timeslice is. It can
- # be defined in a human readable short form -- e.g. "1d", "1y".
- #
- # 'retention' controls how long historical statistics will be kept for.
- # It can be defined in a human readable short form -- e.g. "1d", "1y".
- #
- #
- #stats:
- # enabled: true
- # bucket_size: 1d
- # retention: 1y
+ stats:
+  # Uncomment the following to disable room and user statistics. Note that doing
+  # so may cause certain features (such as the room directory) not to work
+  # correctly.
+  #
+  #enabled: false
+
+  # The size of each timeslice in the room_stats_historical and
+  # user_stats_historical tables, as a time period. Defaults to "1d".
+  #
+  #bucket_size: 1h
  """