Merge pull request #13947 from nextcloud/feat/openmetrics_doc

feat: add documentation for OpenMetrics

Author: come-nc

admin_manual/configuration_monitoring/index.rst

@@ -0,0 +1,43 @@
+==========
+Monitoring
+==========
+
+OpenMetrics
+-----------
+
+.. versionadded:: 33
+
+Nextcloud exposes a ``/metrics`` endpoint. By default, it responds only on localhost.
+You can change this behaviour with ``openmetrics_allowed_clients``
+
+::
+
+  'openmetrics_allowed_clients' => [
+    '192.168.0.0/16',
+  ],
+
+
+.. warning::
+
+   Ensure this endpoint is not accessible to everyone as it could lead to some load on your server.
+
+
+You can view the content of this endpoint with the following command:
+
+::
+
+  curl "https://your.domain/metrics"
+
+
+If for some reason you want to disable some metrics (eg. if they take too long to generate), you can disable them by adding their class name into ``openmetrics_skipped_classes``
+
+::
+
+  'openmetrics_skipped_classes' => [
+    'OC\OpenMetrics\Exporters\FilesByType',
+  ],
+
+
+.. seealso::
+
+ Check :doc:`../configuration_server/config_sample_php_parameters` for more information

admin_manual/contents.rst

@@ -65,6 +65,7 @@ Table of contents
 .. toctree::
     :caption: Maintenance
 
+    configuration_monitoring/index
     maintenance/index
     issues/index
 

admin_manual/release_notes/upgrade_to_33.rst

@@ -25,6 +25,14 @@ Snowflake IDs
 This version of Nextcloud ships with `Snowflake IDs <https://en.wikipedia.org/wiki/Snowflake_ID>`_. Those IDs include the creation time of object, a sequence ID and a server ID.
 The server ID should now be configured in your config.php file or using environment variables. See :doc:`../configuration_server/config_sample_php_parameters` for more information.
 
+OpenMetrics endpoint
+--------------------
+
+Nextcloud 33 introduces a ``/metrics`` endpoint that can be integrated into every OpenMetrics (Prometheus) system.
+For security, it only answers on localhost by default.
+
+See :doc:`../configuration_monitoring/index` for more information about it.
+
 
 Default user agent for outgoing requests changed
 ------------------------------------------------

developer_manual/digging_deeper/index.rst

@@ -24,6 +24,7 @@ Digging deeper
    notifications
    oidc
    out_of_office
+   openmetrics
    performance
    phonenumberutil
    psr

developer_manual/digging_deeper/openmetrics.rst

@@ -0,0 +1,90 @@
+=====================
+Open Metrics exporter
+=====================
+
+.. versionadded:: 33.0
+
+Nextcloud allows to export metrics using `OpenMetrics <https://openmetrics.io/>`_ format.
+
+The data is available on the ``/metrics`` endpoint and can then be imported into any OpenMetrics (formerly Prometheus) enabled tool.
+
+
+Register a new exporter
+-----------------------
+
+Each exporter must be registered inside **<myapp>/appinfo/info.xml**:
+
+.. code-block:: xml
+
+    <openmetrics>
+        <exporter>OCA\MyApp\OpenMetrics\CustomExporter</exporter>
+        <exporter>OCA\MyApp\OpenMetrics\AnotherExporter</exporter>
+    </openmetrics>
+
+
+Implement a new exporter
+------------------------
+
+Then you need to implement it:
+
+.. code-block:: php
+
+    <?php
+
+    declare(strict_types=1)
+
+    namespace OCA\MyApp\OpenMetrics;
+
+    use OCP\OpenMetrics\IMetricFamily;
+    use OCP\OpenMetrics\MetricType;
+
+    class CustomExporter implements IMetricFamily {
+        public function __construct(
+            // Add you dependencies here
+        ) {
+        }
+
+        #[Override]
+        public function name(): string {
+            return 'myapp_metric';
+        }
+
+        #[Override]
+        public function type(): MetricType {
+           // One MetricType::*
+            return MetricType::gauge;
+        }
+
+        #[Override]
+        public function unit(): string {
+            return 'units';
+        }
+
+        #[Override]
+        public function help(): string {
+            return 'Description of metric';
+        }
+
+        #[Override]
+        public function metrics(): Generator {
+            yield new Metric(
+                42,
+                ['label' => 'one value'],
+            );
+            yield new Metric(
+                1337,
+                ['label' => 'another value'],
+            );
+        }
+    }
+
+This exporter will add something like this on the ``/metrics`` endpoint:
+
+.. code-block::
+
+   # TYPE nextcloud_myapp_metric gauge
+   # UNIT nextcloud_myapp_metric units
+   # HELP nextcloud_myapp_metric Description of metric
+   nextcloud_myapp_metric{label="one value"} 42
+   nextcloud_myapp_metric{backend="another value"} 1337
+