Runtime monitoring and health checks

The Semarchy xDI Runtime uses the Spring Boot Actuator library to expose various Runtime metrics. These metrics can be used to monitor the runtime status and health, and can be accessed via HTTP endpoints that return information in JSON format.

For more information about Actuator monitoring, see the Spring Boot documentation.

Configure the Runtime for metrics

Runtime metrics are enabled by default, but most of them cannot be viewed without proper user permissions. An unauthenticated user can only see if the runtime is currently up, and only from devices the runtime allows.

To access metrics, you need to first create a user for authenticated access, and give the user the Monitor or Admin role.

If you want to modify or disable metrics, set the following two Java properties in the XDI_RUNTIME_OPTS environment variable:

Property Description

com.semarchy.xdi.metrics-endpoint

List of endpoints to expose, as a comma-separated list (such as health,metrics). An empty value disables all metrics.

com.semarchy.xdi.monitoring

List of monitoring system metrics to expose, as a comma-separated list (such as prometheus). An empty value disables monitoring support.

Access the metrics

The Spring Boot Actuator library has a specific URL format that starts with /actuator. For example, to check the health of a local runtime open on port 42200, you would use the URL http://localhost:42200/actuator/health.

You can view the list of available metrics and HTTP endpoints, as well as test them, by going to the Swagger UI built into the Runtime:

  1. Start your Runtime directly or from xDI Designer.

  1. In the command line window that appears, find the URL prefaced with HTTP Rest v3 - UI (local url), and open it in your web browser.

    Command line output highlighting the Swagger URL

  1. Go to the Select a definition dropdown at the top right part of the page, and select monitor.

    Swagger dropdown showing monitor entry

  1. The Actuator metrics and endpoints appear on the page.

    Swagger interface showing available Actuator endpoints

General endpoints

This list is an overview of available endpoints, and is not exhaustive. Consult the Swagger UI for all available options.

Table 1. Sample endpoints
Endpoint Description

/actuator

Returns the list of all available endpoints, including itself.

/actuator/health

Global health endpoint.

For authenticated users, returns information about:

  • Runtime UP or DOWN status

  • Disk space information

  • The runtime path on the local filesystem

  • Log database status

  • Scheduler database status, if the scheduler is enabled

For unauthenticated users, only returns UP or DOWN status.

/actuator/metrics

Global metrics endpoint.

By itself, returns a list of metric names that can be used by appending the name to this endpoint in the format /actuator/metrics/<metric_name>.

Invoking a metric by name returns data containing the metric name, description, value, unit of measurement, applicable tags, and other ancillary information.

/actuator/quartz

Quartz Scheduler endpoint.

Use this endpoint to retrieve information about schedules and jobs. You can invoke it when the scheduler is active, in a few ways:

/actuator/quartz

Returns job and trigger groups.

/actuator/quartz/jobs

List all scheduler jobs.

/actuator/quartz/triggers

List all scheduler triggers.

/actuator/quartz/<jobs|triggers>/<group>

List scheduler jobs or triggers from a given group.

/actuator/quartz/<jobs|triggers>/<group>/<name>

Show information about a specific job or trigger.

Invoking a metric by name returns data containing the metric name, description, value, unit of measurement, applicable tags, and other ancillary information.

/actuator/<monitoring_system>

Returns metrics and health information in other formats, as needed by specific monitoring systems.

Monitoring software endpoints

Monitoring system Actuator endpoint Usage

Prometheus

prometheus

Invoke to retrieve metrics in a line-based format for the Prometheus monitoring tool.

Kubernetes

health/liveness
health/readiness

Actuator detects Kubernetes deployments automatically, and activates these health endpoints. Their data is also available from the global health endpoint.

Examples

In the following examples, all URLs and responses were taken from a local xDI Designer runtime.

Root endpoint

URL

http://localhost:42200/actuator/

Example 1. Response
{
  "_links": {
    "self": {
      "href": "http://localhost:42200/actuator",
      "templated": false
    },
    "health-path": {
      "href": "http://localhost:42200/actuator/health/{*path}",
      "templated": true
    },
    "health": {
      "href": "http://localhost:42200/actuator/health",
      "templated": false
    },
    "prometheus": {
      "href": "http://localhost:42200/actuator/prometheus",
      "templated": false
    },
    "metrics-requiredMetricName": {
      "href": "http://localhost:42200/actuator/metrics/{requiredMetricName}",
      "templated": true
    },
    "metrics": {
      "href": "http://localhost:42200/actuator/metrics",
      "templated": false
    }
  }
}

Health check

URL

http://localhost:42200/actuator/health

Example 2. Response (not authenticated)
{
  "status": "UP",
}
Example 3. Response (authenticated user)
{
  "status": "UP",
  "components": {
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 1022086868992,
        "free": 867966222336,
        "threshold": 10485760,
        "path": "C:\\Users\\Semarchy\\apps\\xdi-designer\\2024.1.0\\runtime\\.",
        "exists": true
      }
    },
    "ping": {
      "status": "UP"
    }
  }
}

JVM uptime

URL

http://localhost:42200/actuator/metrics/process.uptime

Example 4. Response
{
  "name": "process.uptime",
  "description": "The uptime of the Java virtual machine",
  "baseUnit": "seconds",
  "measurements": [
    {
      "statistic": "VALUE",
      "value": 9994.231
    }
  ],
  "availableTags": []
}