Rest Monitoring

The REST monitoring implements a Jolokia type functionality in Payara Server.

It exposes MBeans over HTTP with a REST API to stop JMX monitoring requiring RMI. The REST monitoring is hosted on the admin-listener (port 4848).

Configuring REST monitoring

REST monitoring is configurable through several asadmin commands.

Setting REST monitoring Configuration

The set-rest-monitoring-configuration asadmin command is used to configure REST monitoring. This command requires the server to be running. Each configuration property can be configured individually or all together.

asadmin> set-rest-monitoring-configuration --enabled true --target ${config name} --contextRoot ${contextRoot} --name ${RESTMonitoringApplicationName} --securityEnabled true
Option Type Description Default Value Required

--target

String

The config whose values will be set.

server-config

no

--enabled

Boolean

Whether or not the service is enabled for the selected config.

false

no

--contextRoot

String

The context root of the REST Monitoring application.

/rest-monitoring

no

--name

String

The name of the REST Monitoring application.

__restmonitoring

no

--securityEnabled

Boolean

Whether or not secure access to the REST Monitoring application is enabled.

false

no

Rest Monitoring Security

This requires secure admin to be enabled. 
asadmin> set-rest-monitoring-configuration --securityenabled=true

The securityenabled property defines whether the REST monitoring application is available over HTTPS. Since the REST monitoring application is hosted on the admin-listener.

Enabling secure admin can be done by first configuring the admin password with the change-admin-password command, then using the enable-secure-admin command. Enabling secure admin requires a server restart.

When securityenabled is set to true, a username and password is required to use REST monitoring.

The default username is set to payara and the default password is set to rest. The user payara is defined in the file realm.

The password can be changed with the following command:

asadmin> update-file-user --groups=rest --target=server-config --authrealmname=file payara

This updates the payara user, which is part of the rest group. Any users who are able to log in to the REST monitoring must also be defined in the file realm and be part of the rest group.

New users can be created by using the following command:

asadmin> create-file-user --groups=rest --target=server-config --authrealmname=file ${username}

Getting REST monitoring Configuration

asadmin> get-rest-monitoring-configuration

The get-rest-monitoring-configuration asadmin command is used to get the configuration of the REST monitoring. This command requires the server to be running.

If no target is specified, the command will get the REST monitoring configuration from the domain configuration (server-config). The --target option retrieves the REST monitoring from another instance or cluster.

Example Asadmin Output

asadmin> get-rest-monitoring-configuration --target server-config

Enabled    Rest Monitoring Application Name    Context Root       Security Enabled
true       __restmonitoring                    /rest-monitoring   false

Command-Line Options

Option Type Description Default Value Required

--target

String

The config whose REST Monitoring application’s configuration will be retrieved.

server-config

no

Usage

Only the READ Operations are supported currently

Common usage examples with REST Monitoring through Asadmin and admin console.

Enabling Security For Use With HTTPS

The securityenabled property defines whether the REST monitoring application is available over HTTPS. Since the REST monitoring application is hosted on the admin-listener, this requires secure admin to be enabled.

Enabling secure admin requires a server restart.

Enabling Secure REST Monitoring

Once secure admin is enabled, you may enable security for REST Monitoring.

asadmin> set-rest-monitoring-configuration --securityenabled=true

Changing The Default Password

When securityenabled is set to true, a username and password are required to use REST monitoring. By default, the username is set to payara and the password is set to rest. The user payara is defined in the file realm.

The password can be changed with the update-file-user` command

asadmin> update-file-user --groups=rest --target=server-config --authrealmname=file payara

This updates the payara user, which is part of the rest group. Any users who are able to log in to the REST monitoring must also be defined in the file realm and be part of the rest group.

Adding New Users

New users can be added using the create-file-user command.

asadmin> create-file-user --groups=rest --target=server-config --authrealmname=file ${username}

Performing READ Operations

REST Monitoring supports a subset of operations in the Jolokia API.

The read operation reads the details of the requested MBean. The read operation accepts GET requests on URLs in the following format:

<REST_API_URL>/read/${mbean-name}/${attribute-name}

A list of attribute names can be found in the request of an empty attribute name under ‘value’.

Example Execution

To read the MBean java.lang:type=Memory using the default configuration, you would make a GET request to: http://localhost:4848/rest-monitoring/rest/read/java.lang:type=Memory.

Example Output

{
  "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
}

Performing Bulk READ Operations

It is possible to execute bulk operations using the REST monitoring API. To do this, issue a POST request to the REST API URL with the following JSON structure as the body payload.

Example Payload

The payload is a JSON array consisting of objects of type, MBean, and attribute JSON objects. You may send a single operation request instead of an array also.

[
  {
    "type" : "<OPERATION_TYPE>",
    "mbean" : "<MBEAN_NAME>",
    "attribute" : "<ATTRIBUTE_NAME>"
  },
  {
    "type" : "<OPERATION_TYPE>",
    "mbean" : "<MBEAN_NAME>",
    "attribute" : "<ATTRIBUTE_NAME>"
  }
]

  • type - The ‘type’ of operation to execute, e.g. read, search, write, etc.

  • mbean - The MBean attribute which the operation will be executed on.

  • attribute - The MBean attribute upon which the operation will be executed. If omitted, all attributes of the MBean will be involved in the operation.

Example Execution

Using curl and a sample REST API URL of http://localhost:4848/rest-monitoring/rest

curl -X POST \
  http://localhost:4848/rest-monitoring/rest/ \
  -H 'Content-Type: application/json' \
  -d '[
	{
		"mbean": "java.lang:type=Compilation",
		"type": "read"
	},{
		"mbean": "java.lang:type=Runtime",
		"attribute" : "Uptime",
		"type": "read"
	}
]'

Example Output

[
    {
        "request": {
            "mbean": "java.lang:type=Compilation",
            "type": "read"
        },
        "value": {
            "Name": "HotSpot 64-Bit Tiered Compilers",
            "CompilationTimeMonitoringSupported": true,
            "TotalCompilationTime": 106363,
            "ObjectName": "java.lang:type=Compilation"
        },
        "timestamp": 1529353755633,
        "status": 200
    },
    {
        "request": {
            "mbean": "java.lang:type=Runtime",
            "attribute": "Uptime",
            "type": "read"
        },
        "value": 8541422,
        "timestamp": 1529353755636,
        "status": 200
    }
]

See Also

JMX Monitoring