feat: provide a default implemention of metric::get_description

Metric classes no longer need to implement `get_description`.
By default, a string with the ID `"metric:{$name}_desc"` is expected to exist in the language file of the defining component.
Our metrics no longer override that method.
Unit tests are simplified.
Documentation reflects the change.

Author: daniil-berg

README.md

@@ -169,7 +169,6 @@ Let's say we have our own `local_example` plugin and the metric class is suppose
 ```php
 namespace local_example\metrics;
 
-use core\lang_string;
 use tool_monitoring\metric;
 use tool_monitoring\metric_type;
 use tool_monitoring\metric_value;
@@ -182,10 +181,6 @@ class blocks_used extends metric {
         return metric_type::GAUGE;
     }
 
-    public static function get_description(): lang_string {
-        return new lang_string('metric:blocks_used_help', 'local_example');
-    }
-
     public function calculate(): array {
         global $DB;
         [$insql, $params] = $DB->get_in_or_equal(['course_list', 'course_summary']);
@@ -214,20 +209,24 @@ We want to partition the metric by the block _name_ and therefore return an arra
 The description is what is shown in the admin dashboard.
 It is also what the `monitoringexporter_prometheus` exporter uses to generate its metric `HELP` string.
 
-In our example above, we return the [localized string][moodle docs string api] with the ID `metric:blocks_used_help`.
-We just need to actually add the text to be displayed to the plugin's language file.
+By default, a metric is expected to come with a [localized string][moodle docs string api] with the ID `"metric:{$name}_desc"` where `{$name}` is the name of the metric.
+In our example above, there needs to be a string with the ID `metric:blocks_used_desc`.
+So we need to actually add the text to be displayed to the plugin's language file.
 
 <details open>
   <summary><code>lang/en/local_example.php</code> (Click to expand/collapse)</summary>
 
 ```php
 defined('MOODLE_INTERNAL') || die();
 // ...
-$string['metric:blocks_used_help'] = 'Current number of blocks used on the site.';
+$string['metric:blocks_used_desc'] = 'Current number of blocks used on the site.';
 ```
 
 </details>
 
+> [!TIP]
+> You can specify a different string by overriding the `get_description` method in your metric class.
+
 #### Registering the metric
 
 The new metric class needs to be picked up by the `metric_collection` hook.
@@ -367,10 +366,6 @@ class blocks_used extends metric_with_config {
         return metric_type::GAUGE;
     }
 
-    public static function get_description(): lang_string {
-        return new lang_string('metric:blocks_used_help', 'local_example');
-    }
-
     public function calculate(): metric_value {
         global $DB;
         $config = $this->parse_config(blocks_used_config::class);

classes/local/metrics/courses.php

@@ -29,7 +29,6 @@
 
 namespace tool_monitoring\local\metrics;
 
-use core\lang_string;
 use dml_exception;
 use tool_monitoring\metric_type;
 use tool_monitoring\metric;
@@ -48,26 +47,18 @@
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class courses extends metric {
-    /**
-     * {@inheritDoc}
-     */
+    #[\Override]
     public static function get_type(): metric_type {
         return metric_type::GAUGE;
     }
 
     /**
-     * {@inheritDoc}
-     */
-    public static function get_description(): lang_string {
-        return new lang_string('metric:courses_description', 'tool_monitoring');
-    }
-
-    /**
-     * {@inheritDoc}
+     * Produces the current metric values.
      *
-     * @return metric_value[]
+     * @return metric_value[] Two metric values, one for visible courses and one for hidden courses.
      * @throws dml_exception
      */
+    #[\Override]
     public function calculate(): array {
         global $DB;
         $sql = "SELECT SUM(visible)                                 AS numvisible,

classes/local/metrics/overdue_tasks.php

@@ -29,7 +29,6 @@
 
 namespace tool_monitoring\local\metrics;
 
-use core\lang_string;
 use dml_exception;
 use Generator;
 use tool_monitoring\metric;
@@ -52,26 +51,18 @@
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class overdue_tasks extends metric {
-    /**
-     * {@inheritDoc}
-     */
-    public static function get_description(): lang_string {
-        return new lang_string('metric:overdue_tasks_description', 'tool_monitoring');
-    }
-
-    /**
-     * {@inheritDoc}
-     */
+    #[\Override]
     public static function get_type(): metric_type {
         return metric_type::GAUGE;
     }
 
     /**
-     * {@inheritDoc}
+     * Produces the current metric value.
      *
      * @return Generator<metric_value> Yields one {@see metric_value} for adhoc and then one for scheduled tasks.
      * @throws dml_exception
      */
+    #[\Override]
     public function calculate(): Generator {
         global $DB;
         $where = 'nextruntime <= :next_runtime';

classes/local/metrics/quiz_attempts_in_progress.php

@@ -30,7 +30,6 @@
 namespace tool_monitoring\local\metrics;
 
 use core\exception\coding_exception;
-use core\lang_string;
 use dml_exception;
 use tool_monitoring\exceptions\metric_config_not_implemented;
 use tool_monitoring\metric_type;
@@ -53,29 +52,20 @@
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class quiz_attempts_in_progress extends metric_with_config {
-    /**
-     * {@inheritDoc}
-     */
+    #[\Override]
     public static function get_type(): metric_type {
         return metric_type::GAUGE;
     }
 
     /**
-     * {@inheritDoc}
-     */
-    public static function get_description(): lang_string {
-        return new lang_string('metric:quiz_attempts_in_progress_description', 'tool_monitoring');
-    }
-
-    /**
-     * {@inheritDoc}
+     * Produces the current metric value.
      *
-     * @return metric_value
+     * @return metric_value Number of ongoing quiz attempts within the configured time windows.
      * @throws coding_exception
      * @throws dml_exception
      * @throws metric_config_not_implemented
-     * /
      */
+    #[\Override]
     public function calculate(): metric_value {
         global $DB;
         $config = $this->parse_config(quiz_attempts_in_progress_config::class);
@@ -95,9 +85,7 @@ public function calculate(): metric_value {
         );
     }
 
-    /**
-     * {@inheritDoc}
-     */
+    #[\Override]
     public static function get_default_config(): quiz_attempts_in_progress_config {
         return new quiz_attempts_in_progress_config();
     }

classes/local/metrics/user_accounts.php

@@ -29,7 +29,6 @@
 
 namespace tool_monitoring\local\metrics;
 
-use core\lang_string;
 use dml_exception;
 use Generator;
 use tool_monitoring\metric_type;
@@ -49,26 +48,18 @@
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class user_accounts extends metric {
-    /**
-     * {@inheritDoc}
-     */
+    #[\Override]
     public static function get_type(): metric_type {
         return metric_type::GAUGE;
     }
 
     /**
-     * {@inheritDoc}
-     */
-    public static function get_description(): lang_string {
-        return new lang_string('metric:user_accounts_description', 'tool_monitoring');
-    }
-
-    /**
-     * {@inheritDoc}
+     * Produces the current metric values.
      *
      * @return Generator<metric_value> Yields a {@see metric_value} for each combination of auth type and suspended/deleted state.
      * @throws dml_exception
      */
+    #[\Override]
     public function calculate(): Generator {
         global $DB;
         $authtypes = get_enabled_auth_plugins();

classes/local/metrics/users_online.php

@@ -30,7 +30,6 @@
 namespace tool_monitoring\local\metrics;
 
 use core\exception\coding_exception;
-use core\lang_string;
 use dml_exception;
 use tool_monitoring\exceptions\metric_config_not_implemented;
 use tool_monitoring\metric_type;
@@ -50,28 +49,20 @@
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class users_online extends metric_with_config {
-    /**
-     * {@inheritDoc}
-     */
+    #[\Override]
     public static function get_type(): metric_type {
         return metric_type::GAUGE;
     }
 
     /**
-     * {@inheritDoc}
-     */
-    public static function get_description(): lang_string {
-        return new lang_string('metric:users_online_description', 'tool_monitoring');
-    }
-
-    /**
-     * {@inheritDoc}
+     * Produces the current metric values.
      *
      * @return metric_value[] One metric value per configured time window, labeled with that same time window, in ascending order.
      * @throws coding_exception
      * @throws dml_exception
      * @throws metric_config_not_implemented
      */
+    #[\Override]
     public function calculate(): array {
         global $DB;
         $config = $this->parse_config(users_online_config::class);
@@ -97,9 +88,12 @@ public function calculate(): array {
     }
 
     /**
-     * {@inheritDoc}
-     * {@noinspection PhpUnhandledExceptionInspection}
+     * Returns the default config for the metric.
+     *
+     * @return users_online_config Config object.
+     * @throws coding_exception
      */
+    #[\Override]
     public static function get_default_config(): users_online_config {
         return new users_online_config(60, 300, 900, 3600);
     }

classes/metric.php

@@ -30,6 +30,7 @@
 namespace tool_monitoring;
 
 use core\component;
+use core\exception\coding_exception;
 use core\lang_string;
 use tool_monitoring\hook\metric_collection;
 use Traversable;
@@ -88,24 +89,34 @@ public static function collect(metric_collection $hook): static {
     abstract public function calculate(): iterable|metric_value;
 
     /**
-     * Returns the localized description of the metric.
+     * Returns the type of the metric.
      *
-     * @return lang_string Metric description/help text.
+     * @return metric_type
      */
-    abstract public static function get_description(): lang_string;
+    abstract public static function get_type(): metric_type;
 
     /**
-     * Returns the type of the metric.
+     * Returns the localized description of the metric.
      *
-     * @return metric_type
+     * Subclasses may override this. Defaults to a language string with the ID `"metric:{$name}_desc"` where `$name` is the
+     * metric's name as returned by the {@see static::get_name `get_name`} method, residing in the language file of the defining
+     * component as returned by the {@see static::get_component `get_component`} method.
+     *
+     * @return lang_string Metric description/help text.
+     * @throws coding_exception
      */
-    abstract public static function get_type(): metric_type;
+    public static function get_description(): lang_string {
+        $name = static::get_name();
+        return new lang_string("metric:{$name}_desc", static::get_component());
+    }
 
     /**
      * Returns the name of the metric to be used as an identifier.
      *
      * Subclasses may override this. It _should_ be descriptive and only consist of letters and underscores; it _must_ be unique for
-     * the defining component as returned by {@see get_component}; it _must_ be a maximum of 100 characters long.
+     * the defining component as returned by the {@see static::get_component `get_component`} method; it _must_ be no longer than
+     * 100 characters.
+     *
      * Defaults to the unqualified class name.
      *
      * @return string Unique metric name/identifier.
@@ -119,7 +130,7 @@ public static function get_name(): string {
     }
 
     /**
-     * Returns the name of the Moodle component, i.e. the plugin or core component, which defines this metric.
+     * Returns the name of the Moodle component/plugin, which defines the metric.
      *
      * @return string Moodle component name.
      */

lang/en/tool_monitoring.php

@@ -44,17 +44,17 @@
 $string['event:metric_disabled'] = 'Metric disabled';
 $string['event:metric_enabled'] = 'Metric enabled';
 
-$string['metric:courses_description'] = 'Current number of courses';
-$string['metric:overdue_tasks_description'] = 'Number of tasks (excluding disabled ones) for which the next runtime is not in the future';
+$string['metric:courses_desc'] = 'Current number of courses';
+$string['metric:overdue_tasks_desc'] = 'Number of tasks (excluding disabled ones) for which the next runtime is not in the future';
 $string['metric:quiz_attempts_in_progress_config:maxdeadlineseconds'] = 'Maximum deadline time';
 $string['metric:quiz_attempts_in_progress_config:maxdeadlineseconds_help'] = 'Do not count attempts that have a deadline in more than this number of seconds.';
 $string['metric:quiz_attempts_in_progress_config:maxidleseconds'] = 'Maximum idle time';
 $string['metric:quiz_attempts_in_progress_config:maxidleseconds_help'] = 'Do not count attempts that are idle longer than this number of seconds.';
-$string['metric:quiz_attempts_in_progress_description'] = 'Number of ongoing quiz attempts with an approaching deadline';
-$string['metric:user_accounts_description'] = 'Current number of user accounts';
+$string['metric:quiz_attempts_in_progress_desc'] = 'Number of ongoing quiz attempts with an approaching deadline';
+$string['metric:user_accounts_desc'] = 'Current number of user accounts';
 $string['metric:users_online_config:timewindows'] = 'Time window (seconds)';
 $string['metric:users_online_config:timewindows_help'] = 'Number of seconds since the last user access for that user to be counted as online. Multiple values can be specified, separated by commas; the metric will produce a separate metric value for each time window.';
-$string['metric:users_online_description'] = 'Number of users that have recently accessed the site';
+$string['metric:users_online_desc'] = 'Number of users that have recently accessed the site';
 
 $string['monitoring:manage_metrics'] = 'Manage and configure monitoring metrics';
 

tests/local/metrics/courses_test.php

@@ -55,13 +55,6 @@ public function test_get_type(): void {
         self::assertSame(metric_type::GAUGE, $metric->get_type());
     }
 
-    public function test_get_description(): void {
-        $metric = new courses();
-        $description = $metric->get_description();
-        self::assertSame('metric:courses_description', $description->get_identifier());
-        self::assertSame('tool_monitoring', $description->get_component());
-    }
-
     public function test_calculate(): void {
         $this->resetAfterTest();
         $generator = $this->getDataGenerator();

tests/local/metrics/overdue_tasks_test.php

@@ -66,13 +66,6 @@ public function test_get_type(): void {
         self::assertSame(metric_type::GAUGE, $metric->get_type());
     }
 
-    public function test_get_description(): void {
-        $metric = new overdue_tasks();
-        $description = $metric->get_description();
-        self::assertSame('metric:overdue_tasks_description', $description->get_identifier());
-        self::assertSame('tool_monitoring', $description->get_component());
-    }
-
     public function test_calculate(): void {
         global $DB;
         $this->resetAfterTest();