diff --git a/admin_manual/configuration_monitoring/index.rst b/admin_manual/configuration_monitoring/index.rst new file mode 100644 index 00000000000..d60c53e3914 --- /dev/null +++ b/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 soime metrics (eg. if they take too long to generate), you can disable some of them using 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 diff --git a/admin_manual/contents.rst b/admin_manual/contents.rst index 6442113fb16..29a833bebbf 100644 --- a/admin_manual/contents.rst +++ b/admin_manual/contents.rst @@ -65,6 +65,7 @@ Table of contents .. toctree:: :caption: Maintenance + configuration_monitoring/index maintenance/index issues/index diff --git a/admin_manual/release_notes/upgrade_to_33.rst b/admin_manual/release_notes/upgrade_to_33.rst index 428c10f4c99..45120582e2d 100644 --- a/admin_manual/release_notes/upgrade_to_33.rst +++ b/admin_manual/release_notes/upgrade_to_33.rst @@ -25,6 +25,14 @@ Snowflake IDs This version of Nextcloud ships with `Snowflake IDs `_. 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 introduce a ``/metrics`` endpoint that can be integrated into every OpenMetrics (Prometheus) system. +For security, it only answer on localhost by default. + +See :doc:`../configuration_monitoring/index` for more information about it. + Default user agent for outgoing requests changed ------------------------------------------------ diff --git a/developer_manual/digging_deeper/index.rst b/developer_manual/digging_deeper/index.rst index 0f152d42016..4f516d42cb9 100644 --- a/developer_manual/digging_deeper/index.rst +++ b/developer_manual/digging_deeper/index.rst @@ -24,6 +24,7 @@ Digging deeper notifications oidc out_of_office + openmetrics performance phonenumberutil psr diff --git a/developer_manual/digging_deeper/openmetrics.rst b/developer_manual/digging_deeper/openmetrics.rst new file mode 100644 index 00000000000..ee993a57fcc --- /dev/null +++ b/developer_manual/digging_deeper/openmetrics.rst @@ -0,0 +1,90 @@ +===================== +Open Metrics exporter +===================== + +.. versionadded:: 33.0 + +Nextcloud allows to export metrics using `OpenMetrics `_ 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 **/appinfo/info.xml**: + +.. code-block:: xml + + + OCA\MyApp\OpenMetrics\CustomExporter + OCA\MyApp\OpenMetrics\AnotherExporter + + + +Implement a new exporter +------------------------ + +Then you need to implement it: + +.. code-block:: php + + '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 +