From 76a5077e748521d4bac3dd85b0bc1e962cef61ff Mon Sep 17 00:00:00 2001 From: Andrea Di Cesare Date: Mon, 18 Sep 2023 17:06:54 +0200 Subject: [PATCH] :sparkles: Add doc page /docs/monitoring --- _includes/docs-sidebar.html | 2 +- docs/mongodb-rest/monitoring.md | 4 + docs/monitoring.adoc | 142 ++++++++++++++++++++++++++++++++ 3 files changed, 147 insertions(+), 1 deletion(-) create mode 100644 docs/monitoring.adoc diff --git a/_includes/docs-sidebar.html b/_includes/docs-sidebar.html index d0f47e5a..e29bc9eb 100644 --- a/_includes/docs-sidebar.html +++ b/_includes/docs-sidebar.html @@ -26,6 +26,7 @@

Setup

  • Proxying requests
  • Serving static resources
  • Logging
    • +
  • Monitoring
  • Auditing
  • Clustering & Load Balancing
  • Enterprise License
    • @@ -83,7 +84,6 @@

    REST API

  • Transactions
  • ETag
  • Shard Keys
    • -
  • Monitoring

    • GraphQL API

    diff --git a/docs/mongodb-rest/monitoring.md b/docs/mongodb-rest/monitoring.md index be705a61..a83a2798 100644 --- a/docs/mongodb-rest/monitoring.md +++ b/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 diff --git a/docs/monitoring.adoc b/docs/monitoring.adoc new file mode 100644 index 00000000..062998b4 --- /dev/null +++ b/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 =`. 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 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.