REST Monitoring in Payara Server

The Payara Server 173 release included a technical preview of the REST Monitoring Service, which is a service to expose JMX monitoring MBeans over HTTP. As of Payara Server 174, this feature is no longer in tech preview.

One big problem with JMX is that JMX monitoring uses RMI (Remote Method Invocation), which can lead to a few nightmares if, for example, you have a firewall which blocks connections over RMI ports. The REST monitoring service in Payara Server now provides a service which will be very familiar to users of Jolokia in that it makes this monitoring data available over HTTP, making the data available in a more standard format (JSON) and accessible over a standard HTTP connection.

In Payara Server 173, the REST monitoring service is referred to as Payara Fang. This means that where for example Payara Server 174 and above will have commands like get-rest-monitoring-configuration, Payara Server 173 will instead use get-payara-fang-configuration.

Quick Start

The quickest way to begin working with the REST Monitoring service is as follows

1. Run this asadmin command in your terminal:
   

   1. asadmin> set-rest-monitoring-configuration --enabled true
      
2. View data by going to http://localhost:4848/rest-monitoring/rest/read/java.lang:type=Memory to get a JSON representation of the MBean called “java.lang:type=Memory“.

Explained

You can find full usage details and help from our documentation. Configuring REST monitoring is as simple as running the “set-rest-monitoring-configuration” command with “--enabled=true” from asadmin. The REST monitoring application is deployed to the admin listener with the default context root “/rest-monitoring” (or “/fang” if you’re using Payara Server 173). You can however configure this context root to be whatever you want with “--contextroot=/something“, and the REST API will be accessible from that context root with “/rest” on the end. So by default the REST API is hosted at “/rest-monitoring/rest“.

The general format for REST monitoring URLs is ${base-url}/${operation-name}/${parameters}. Currently the only supported operation is read, although more will be added in future. To read an MBean you will need the name of the MBean to pass as a parameter. So to get the MBean “java.lang:type=Memory” we make a GET request to 

http://localhost:4848/rest-monitoring/rest/read/java.lang:type=Memory,

which will result in a JSON response similar to the following:

{
  "request": {
    "mbean": "java.lang:type=Memory",
    "type": "read"
  },
  "value": {
    "HeapMemoryUsage": {
      "committed": 450363392,
      "init": 264241152,
      "max": 477626368,
      "used": 97480984
    },
    "ObjectPendingFinalizationCount": 0,
    "NonHeapMemoryUsage": {
      "committed": 139460608,
      "init": 2555904,
      "max": -1,
      "used": 122389432
    },
    "Verbose": false,
    "ObjectName": "java.lang:type=Memory"
  },
  "timestamp": 1502799650273,
  "status": 200
}

You can also get the individual attributes returned by a composite MBean. So for the output above you can get a breakdown of each attribute in the array “value”. For example, going to 

http://localhost:4848/rest-monitoring/rest/read/java.lang:type=Memory/HeapMemoryUsage 

gives you the following output:

{
  "request": {
    "mbean": "java.lang:type=Memory",
    "attribute": "HeapMemoryUsage",
    "type": "read"
  },
  "value": {
    "committed": 2147483648,
    "init": 2147483648,
    "max": 2147483648,
    "used": 365953024
  },
  "timestamp": 1502886044406,
  "status": 200
}

 {{cta(‘f53ec10a-12d5-483b-b089-2d4cdab10448’)}}