feat: add performance-monitor controls to Metrics service (v11-only)

Mirror the Performance Monitor on/off/read controls onto MetricService,
delegating to ServerService, since the v11 }Stats* read paths depend on
the monitor running.

- ServerService: add get_performance_monitor_state(); guard start/stop/get
  with @deprecated_in_version("12.0.0") since PerformanceMonitorOn is a
  v11-only config parameter (previously start/stop silently ran on v12)
- MetricService: thin start_/stop_/get_performance_monitor_state delegates,
  same v12 guard; update by_rule hint + class docstring example
- Tests: v11 toggle round-trip, metrics<->server agreement, v12 raises

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: nicolasbisurgi

TM1py/Services/MetricService.py

@@ -31,7 +31,7 @@
 import itertools
 import warnings
 from datetime import datetime
-from typing import Dict, List, Optional, Tuple
+from typing import TYPE_CHECKING, Dict, List, Optional, Tuple
 
 from TM1py.Exceptions.Exceptions import TM1pyVersionException
 from TM1py.Services.CellService import CellService
@@ -42,12 +42,16 @@
     CaseAndSpaceInsensitiveDict,
     build_url_friendly_object_name,
     datetime_to_iso,
+    deprecated_in_version,
     format_url,
     require_pandas,
     require_version,
     verify_version,
 )
 
+if TYPE_CHECKING:
+    from TM1py.Services.ServerService import ServerService
+
 V12_VERSION = "12.0.0"
 
 CATEGORY_BY_CUBE = "by_cube"
@@ -687,8 +691,11 @@ class MetricService(ObjectService):
 
     Per-rule timing (entity-wide), unified across versions — the read is
     identical; only how ``}StatsByRule`` gets populated differs. On v11 the
-    Performance Monitor populates it, so you just read::
+    Performance Monitor populates it, so ensure it is running, then read::
 
+        >>> tm1.metrics.get_performance_monitor_state()
+        False
+        >>> tm1.metrics.start_performance_monitor()
         >>> tm1.metrics.by_rule(cube="plan_BudgetPlan")
 
     On v12 collect on demand: start, exercise the cube's rules, let the ~60s
@@ -715,6 +722,7 @@ def __init__(self, rest: RestService):
         super().__init__(rest)
         self._cells = None
         self._cubes = None
+        self._servers = None
 
     @property
     def _cell_service(self) -> CellService:
@@ -728,6 +736,14 @@ def _cube_service(self) -> CubeService:
             self._cubes = CubeService(self._rest)
         return self._cubes
 
+    @property
+    def _server_service(self) -> "ServerService":
+        if self._servers is None:
+            from TM1py.Services.ServerService import ServerService
+
+            self._servers = ServerService(self._rest)
+        return self._servers
+
     @property
     def _is_v12(self) -> bool:
         return verify_version(required_version=V12_VERSION, version=self.version)
@@ -811,8 +827,8 @@ def by_rule(self, cube: str = None, **kwargs) -> List[Dict]:
                 )
             else:
                 hint = (
-                    "rule stats have not been collected — ensure Performance Monitor is running "
-                    "(ServerService.start_performance_monitor)"
+                    "rule stats have not been collected — ensure the Performance Monitor is running "
+                    "(start_performance_monitor)"
                 )
             warnings.warn(
                 f"'{self.STATS_BY_RULE_CUBE}' does not exist; {hint}. Returning no records.",
@@ -861,6 +877,39 @@ def by_cube_by_client(self, cube: str = None, **kwargs) -> List[Dict]:
     def by_cube_by_client_as_dataframe(self, *args, **kwargs) -> "pd.DataFrame":
         return pd.DataFrame.from_records(self.by_cube_by_client(*args, **kwargs))
 
+    # ------------------------------------------------------------------ #
+    # performance monitor (v11-only: populates the }Stats* cubes while it runs)
+    # ------------------------------------------------------------------ #
+
+    @deprecated_in_version(version="12.0.0")
+    def start_performance_monitor(self):
+        """Turn the Performance Monitor on (v11 only).
+
+        While it runs, TM1 populates the ``}Stats*`` cubes that :meth:`by_cube`,
+        :meth:`by_server`, and :meth:`by_rule` read on v11. ``PerformanceMonitorOn``
+        is a v11-only setting, so this raises :class:`TM1pyVersionDeprecationException`
+        on v12. Delegates to :meth:`ServerService.start_performance_monitor`.
+        """
+        return self._server_service.start_performance_monitor()
+
+    @deprecated_in_version(version="12.0.0")
+    def stop_performance_monitor(self):
+        """Turn the Performance Monitor off (v11 only).
+
+        Raises :class:`TM1pyVersionDeprecationException` on v12. Delegates to
+        :meth:`ServerService.stop_performance_monitor`.
+        """
+        return self._server_service.stop_performance_monitor()
+
+    @deprecated_in_version(version="12.0.0")
+    def get_performance_monitor_state(self) -> bool:
+        """Return whether the Performance Monitor is currently active (v11 only).
+
+        Raises :class:`TM1pyVersionDeprecationException` on v12. Delegates to
+        :meth:`ServerService.get_performance_monitor_state`.
+        """
+        return self._server_service.get_performance_monitor_state()
+
     # ------------------------------------------------------------------ #
     # v12 rule-stats collection lifecycle (cube-bound actions)
     # ------------------------------------------------------------------ #

TM1py/Services/ServerService.py

@@ -254,14 +254,28 @@ def delete_persistent_feeders(self, **kwargs) -> Response:
         process_service = ProcessService(self._rest)
         return process_service.execute_ti_code(ti, **kwargs)
 
+    @deprecated_in_version(version="12.0.0")
     def start_performance_monitor(self):
         config = {"Administration": {"PerformanceMonitorOn": True}}
         self.configuration.update_static(config)
 
+    @deprecated_in_version(version="12.0.0")
     def stop_performance_monitor(self):
         config = {"Administration": {"PerformanceMonitorOn": False}}
         self.configuration.update_static(config)
 
+    @deprecated_in_version(version="12.0.0")
+    def get_performance_monitor_state(self) -> bool:
+        """Read whether the Performance Monitor is currently active.
+
+        The ``PerformanceMonitorOn`` parameter is a v11-only configuration
+        setting; this raises :class:`TM1pyVersionDeprecationException` on v12.
+
+        :return: True if ``PerformanceMonitorOn`` is enabled, otherwise False
+        """
+        config = self.get_active_configuration()
+        return bool(config.get("Administration", {}).get("PerformanceMonitorOn", False))
+
     def activate_audit_log(self):
         self.audit_logs.activate()
 

Tests/MetricService_test.py

@@ -19,7 +19,10 @@
 from pathlib import Path
 
 from TM1py import TM1Service
-from TM1py.Exceptions.Exceptions import TM1pyVersionException
+from TM1py.Exceptions.Exceptions import (
+    TM1pyVersionDeprecationException,
+    TM1pyVersionException,
+)
 from TM1py.Services.MetricService import (
     ALL_TIME_INTERVALS,
     CATEGORY_BY_CUBE,
@@ -761,6 +764,42 @@ def test_lifecycle_methods_require_v12(self):
         with self.assertRaises(TM1pyVersionException):
             tm1.metrics.start_collecting_rule_stats("plan_BudgetPlan")
 
+    # ---------------- performance monitor ---------------- #
+
+    def test_performance_monitor_toggle_v11(self):
+        # the metrics service mirrors the ServerService controls; toggling round-
+        # trips and the state getter reflects each change. Restore the original
+        # state so the suite leaves the server as it found it.
+        tm1 = self._v11()
+        original = tm1.metrics.get_performance_monitor_state()
+        self.assertIsInstance(original, bool)
+        try:
+            tm1.metrics.start_performance_monitor()
+            self.assertTrue(tm1.metrics.get_performance_monitor_state())
+            tm1.metrics.stop_performance_monitor()
+            self.assertFalse(tm1.metrics.get_performance_monitor_state())
+        finally:
+            if original:
+                tm1.metrics.start_performance_monitor()
+            else:
+                tm1.metrics.stop_performance_monitor()
+
+    def test_performance_monitor_delegates_to_server_service(self):
+        # metrics and server services must agree on the current state
+        tm1 = self._v11()
+        self.assertEqual(
+            tm1.metrics.get_performance_monitor_state(),
+            tm1.server.get_performance_monitor_state(),
+        )
+
+    def test_performance_monitor_methods_deprecated_on_v12(self):
+        # PerformanceMonitorOn is a v11-only setting; the controls must refuse v12
+        tm1 = self._v12()
+        for method in ("start_performance_monitor", "stop_performance_monitor", "get_performance_monitor_state"):
+            with self.subTest(method=method):
+                with self.assertRaises(TM1pyVersionDeprecationException):
+                    getattr(tm1.metrics, method)()
+
 
 if __name__ == "__main__":
     unittest.main()