✨ Add doc page /docs/monitoring

_includes/docs-sidebar.html

@@ -26,6 +26,7 @@ <h2 class="mt-2">Setup</h2>
     <li><a href="/docs/proxy">Proxying requests</a></li>
     <li><a href="/docs/static-resources">Serving static resources</a></li>
     <li><a href="/docs/logging">Logging</a></li>
+    <li><a href="/docs/monitoring">Monitoring</a></li>
     <li><a href="/docs/auditing">Auditing</a></li>
     <li><a href="/docs/clustering">Clustering &amp; Load Balancing</a></li>
     <li><a href="/docs/enterprise-license">Enterprise License</a></li>
@@ -83,7 +84,6 @@ <h3 id="rest-api" class="mt-2">REST API</h2>
     <li><a href="/docs/mongodb-rest/transactions">Transactions</a></li>
     <li><a href="/docs/mongodb-rest/etag">ETag</a></li>
     <li><a href="/docs/mongodb-rest/shard-keys">Shard Keys</a></li>
-    <li><a href="/docs/mongodb-rest/monitoring">Monitoring</a></li>
 
 
     <h3 id="rest-api" class="mt-2">GraphQL API</h3>

docs/mongodb-rest/monitoring.md

@@ -20,6 +20,10 @@ menu: mongodb
 
 {% include docs-head.html %}
 
+## Removed starting v7.5
+
+The MongoService monitoring feature has been replaced with generic the [Monitoring](/docs/monitoring) feature starting form RESTHeart v7.5
+
 ## Introduction
 
 Gathering metrics about your production (and staging) environments can

docs/monitoring.adoc

@@ -0,0 +1,142 @@
+---
+title: Monitoring
+layout: docs-adoc
+menu: setup
+---
+
+## Introduction
+
+NOTE: Available from v7.5. For earlier releases only requests handled by the `MongoService` can be monitored, see link:/docs/mongodb-rest/monitoring[Monitoring MongoService requests]
+
+RESTHeart allows monitoring different KPIs on http requests and the JVM, using the leading
+open-source monitoring solution link:https://prometheus.io/[Prometheus].
+
+The following requests metrics are collected by RESTHeart:
+
+- http_requests_count
+- http_requests_duration
+- http_requests_rate
+
+RESTHeart also collects metrics about the JVM, including memory usage and the garbage collector.
+
+## Tutorial
+
+Run restheart enabling metrics and specifying a configuration:
+
+[source,bash]
+----
+$ docker run --rm -p "8080:8080" -e RHO="/http-listener/host->'0.0.0.0';/mclient/connection-string->'mongodb://host.docker.internal';/ping/uri->'/acme/ping';/requestsMetricsCollector/enabled->true;/jvmMetricsCollector/enabled->true;/requestsMetricsCollector/include->['/{tenant}/*']" softinstigate/restheart
+----
+
+Let's analyze the metrics configuration. With the given `RHO` env variable, it is:
+
+[source,yml]
+----
+ping:
+  uri: /acme/ping # change the ping service uri for testing purposes
+requestsMetricsCollector:
+  enabled: true
+  uri: /metrics
+  include:
+    - /{tenant}/*
+  exclude:
+    - /metrics
+    - /metrics/*
+jvmMetricsCollector:
+  enabled: true
+----
+
+Metrics will be collected for requests matching the `include` path templates and not matching the `exclude` ones.
+
+NOTE: the variable `{tenant}` in the include path templates makes the metrics being tagged with `path_template_param_tenant =<value>`. This does not apply for wildcards in path templates.
+
+Let's make a few requests to `/acme/ping` with httpie
+
+[source,bash]
+----
+$ http -b :8080/acme/ping
+Greetings from RESTHeart!
+
+$http -b :8080/acme/ping
+Greetings from RESTHeart!
+
+$http -b :8080/acme/ping
+Greetings from RESTHeart!
+----
+
+Now we can ask for available metrics:
+
+[source,bash]
+----
+$ http -b -a admin:secret :8080/metrics
+[
+    "/jvm",
+    "/{tenant}/ping"
+]
+----
+
+Let's get the metrics for requests matching `"/{tenant}/*"`:
+
+[source,bash]
+----
+$ http -b -a admin:secret :8080/metrics/{tenant}/\*
+
+(omitting many rows)
+http_requests_count{request_method="GET",path_template="/{tenant}/*",response_status_code="200",path_template_param_tenant="acme",} 3.0
+----
+
+The response is in prometheus format. The highlighted row is the metrics `http_requests_count` with value `3` and the following tags:
+
+[source,bash]
+----
+request_method="GET"
+path_template="/{tenant}/*"
+response_status_code="200",
+path_template_param_tenant="acme"
+----
+
+## Use prometheus to display metrics
+
+Define the following prometheus configuration file `prometheus.yml`
+
+[source,yml]
+----
+global:
+  scrape_interval: 5s
+  evaluation_interval: 5s
+
+scrape_configs:
+  - job_name: 'restheart http /{tenant}/*'
+    static_configs:
+    - targets: ['host.docker.internal:8080']
+    metrics_path: '/metrics/{tenant}/*'
+    basic_auth:
+      username: admin
+      password: secret
+  - job_name: 'restheart jvm'
+    static_configs:
+    - targets: ['host.docker.internal:8080']
+    metrics_path: '/metrics/jvm'
+    basic_auth:
+      username: admin
+      password: secret
+----
+
+Run prometheus with:
+
+[source,bash]
+----
+$ docker run --rm --name prometheus -p 9090:9090 -v ./prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus --config.file=/etc/prometheus/prometheus.yml
+----
+
+Prometheus will start scraping restheart metrics. Note that given the default `exclude` path templates, metrics for prometheus requests will not be collected.
+
+Open `localhosts:9090` with your browser and check the metrics:
+
+image::https://github.com/SoftInstigate/restheart/assets/6876503/154b3e6c-bc42-4751-af2d-7e2928746fa4[restheart metrics shown in prometheus]
+
+## Add custom metrics labels from a Service
+
+The method `org.restheart.metrics.Metrics.attachMetricLabels(Request<?> request, List<MetricLabel> labels)` allows to add custom labels to the collected metrics.
+
+This is used, for instance, by `GraphQLService` to add to the metrics the `query` label with the name of the GraphQL executed query.