Skip to content

JaxRsActuator

Jump to bottom
Zoltan Farkas edited this page Aug 17, 2021 · 15 revisions

Another Actuator for JAX-RS

Overview

A JAX-RS actuator is a collection of REST endpoints that help operating your microservice. When using JAX-RS one of the ways to leverage eclipse microprofile distributions (like openliberty.io), and have health, metrics, etc readily available in your application. However if you prefer to be in control (or don't think 100+Mb is justified for this), it is trivial to build your own using JAX-RS, and this article will provide you an example on how you can do that with the folowing endpoints:

  • /info - to serve basic informations about your application.
  • /apiBrowser - to browse you api documentation (Open API) and try it out.
  • /logs - to serve you application logs.
  • /health - to serve your app health status.
  • /jmx - a REST-ful adapter to your app JMX api.
  • /profiles - to serve and visaulize your application profile data.
  • /metrics - to serve your spf4j application metrics.

What is special about all of the above?

  • json and binary support on all rest endpoints. (depending on your Accept header)
  • all endpoints are cluster aware. (you can see ann agregated view of all your logs for all the nodes, access JMX from all your nodes, health with cluster level health checks...)

Getting started

Add the following dependencies to your application:

    <dependency>
      <groupId>org.spf4j</groupId>
      <artifactId>spf4j-jaxrs-actuator</artifactId>
      <version>LATEST</version>
    </dependency>
    <dependency> <!-- the cluster functionality (/logs/cluster, /health/cluster, etc...)-->
      <groupId>org.spf4j</groupId>
      <artifactId>spf4j-jaxrs-actuator-cluster</artifactId>
      <version>LATEST</version>
    </dependency>

Initialize your JerrseyService:

    ...
    JerseyService svc = new JerseyServiceBuilder(jvm)
            .withFeature(ClusterActuatorFeature.class)
            .withFeature(ApiBrowserFeature.class)
    ...

A full example app you can find at.

The features

The Info endpoint

This endpoint provides basic application information like:

{
  "appInfo": {
    "name": "jaxrs-spf4j-demo",
    "description": "A Jax-Rs REST service demo app",
    "site": "https://github.com/zolyfarkas/jaxrs-spf4j-demo"
   },
   "processes": [
      {
        "instanceId": "1@jaxrs-spf4j-demo-b749b8d4-fgmj5:36d0305",
        "name": "1@jaxrs-spf4j-demo-b749b8d4-fgmj5",
        "hostName": "jaxrs-spf4j-demo-b749b8d4-fgmj5",
        "processId": 1,
        "jreVersion": "11.0.4",
        "appVersion": "0.7-SNAPSHOT",
        "buildId": "319657b73031a3ceda3a0fc5cd4df59a2eee6e53",
        "buildTimeStamp": "2019-08-29T15:08:06Z",
        "networkServices": [
        {
        "name": "http",
        "port": 8080,
        "netProtocol": "TCP"
        }
        ]
      },
      {
        "instanceId": "1@jaxrs-spf4j-demo-b749b8d4-dg5m8:36d88c6",
        "name": "1@jaxrs-spf4j-demo-b749b8d4-dg5m8",
        "hostName": "jaxrs-spf4j-demo-b749b8d4-dg5m8",
        "processId": 1,
        "jreVersion": "11.0.4",
        "appVersion": "0.7-SNAPSHOT",
        "buildId": "319657b73031a3ceda3a0fc5cd4df59a2eee6e53",
        "buildTimeStamp": "2019-08-29T15:08:06Z",
        "networkServices": [
        {
        "name": "http",
        "port": 8080,
        "netProtocol": "TCP"
        }
        ]
      }
]
}

The apiBrowser

This endpoint serves you the swagger UI, and allows you to see the documentation of your application endpoints along with your actuator enpoints.

[The logs endpoint]

The logs of your app have never been so easy to access. aggregated across the cluster, filterable, all without a log aggregator. Reducing the data movement in your system will make your system more scalable and more performant. This approach used together with a log aggregator can give you more flexibility on how you can setup your operations.

images

You can also easilly tail your cluster logs, or you can retrieve filter for your non-operational logs /logs/cluster

Here is how you can get your top slowest requests.

You can also get all you profiled request data.

You can use the spf4j-ui to visualize the profile data like:

images

images

You can also aceess the raw log files via the /logFiles/cluster endpoint.

The health endpoint

The health point allows you to run some health checks in order to provide informations about your system health to monitoring systems (like kubernetes liveness or readyness probes).

The health actuator ships ith some default checks like:

  • cluster check: runs the heath checks for all your cluster memebers.

  • deadlock check: runs a thread deadlock check on your jvm.

    You can also register your application specific heath checks by simply creating a heath check registration like:

        bind(HealthCheck.Registration.from("custom", new MyCustomCheck()))
          .to(HealthCheck.Registration.class);

The JMX interface

This is a REST-ful adapter to your application JMX exported operations and variables. See for the API docs.

Profiling endpoint

This endpoint allows you to visualize request attributed profile information and aggregated profile information. See and see for more more detail. Example:

images

Metrics endpoint

This endpoint allows you to get to your cluster or node metrics, and get them in any format you might need: json, avro binary or csv or prometheus

You can also query your metrics more precisely:

Clone this wiki locally