Monitoring

RESTHeart enables the tracking of various key performance indicators (KPIs) for HTTP requests and the JVM. These metrics can be accessed through an API in Prometheus format, enabling you to query and visualize graphs using Prometheus.

The following HTTP requests metrics are collected by RESTHeart:

http_requests_count (Count of HTTP requests)
http_requests_duration (Duration of HTTP requests)
http_requests_rate (Rate of HTTP requests)

Additionally, RESTHeart captures JVM metrics such as memory usage and garbage collector data.

Tutorial

Run restheart enabling metrics and specifying a configuration:

$ 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

With the given RHO env variable, the configuration is:

ping:
  uri: /acme/ping # change the ping service uri for testing purposes
metrics:
  enabled: true
  uri: /metrics
requestsMetricsCollector:
  enabled: true
  include:
    - /{tenant}/*
  exclude:
    - /metrics
    - /metrics/*
jvmMetricsCollector:
  enabled: true

Metrics will be gathered for requests that match the path templates specified in the include criteria and do not match those listed in the exclude criteria.

Please note that when using the variable {tenant} in the include path templates, the metrics will be tagged with path_template_param_tenant=<value>. This tagging does not apply when using wildcards in path templates.

Now, let’s proceed by making a few requests to /acme/ping using httpie.

$ 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:

$ http -b -a admin:secret :8080/metrics
[
    "/jvm",
    "/{tenant}/ping"
]

Let’s get the metrics for requests matching "/{tenant}/*":

$ 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:

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

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:

$ 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 are not collected.

Open localhost:9090 with your browser and check the metrics:

Add custom metrics labels from a Service

The org.restheart.metrics.Metrics.attachMetricLabels(Request<?> request, List<MetricLabel> labels) method provides the capability to include custom labels in the metrics that are being collected.

For example, the GraphQLService utilizes this method to include the query label in the metrics, which corresponds to the name of the executed GraphQL query.