feat: add documentation for OpenMetrics

admin_manual/configuration_monitoring/index.rst

@@ -0,0 +1,24 @@
+==========
+Monitoring
+==========
+
+OpenMetrics
+-----------
+
+.. versionadded:: 33
+
+Nextcloud exposes a ``/metrics`` endpoint. By default, it responds only on localhost.
+You can change this behaviour with :ref:`OpenMetrics configuration<label_openmetrics_config>`.
+
+.. note:
+
+   Please 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"
+
+

admin_manual/configuration_server/config_sample_php_parameters.rst

@@ -3290,6 +3290,40 @@ hashingCost
 The hashing cost used by hashes generated by Nextcloud
 Using a higher value requires more time and CPU power to calculate the hashes
 
+.. _label_openmetrics_config:
+
+OpenMetrics exporter
+--------------------
+
+Nextcloud exposes some OpenMetrics metrics on the ``/metrics`` endpoint.
+
+openmetrics_allowed_clients
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:: 
+
+  'openmetrics_allowed_clients' => [
+    '192.168.0.0/16',
+    'fe80::/10',
+    '10.0.0.1',
+  ];
+
+By default, Nextcloud metrics are only sent to localhost clients.
+This option allows to allow other clients by range or single IP address.
+
+openmetrics_skipped_classes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+:: 
+
+  'openmetrics_skipped_classes' => [
+    'OC\OpenMetrics\Exporters\FilesByType',
+    'OCA\Files_Sharing\OpenMetrics\SharesCount',
+  ];
+
+Some metrics can be time consumming and not useful for you.
+In this case, you can skip some metrics by using their full classname.
+
+
 All other configuration options
 -------------------------------
 

admin_manual/contents.rst

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

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\MetricTypes;
+
+    class CustomExporter implements IMetricFamily {
+        public function __construct(
+            // Add you dependencies here
+        ) {
+        }
+
+        #[Override]
+        public function name(): string {
+          return 'myapp_metric';
+        }
+
+        #[Override]
+        public function type(): MetricTypes {
+            // One MetricTypes::*
+            return MetricTypes::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
+