Monitoring

Available monitoring beans

For monitoring the current status of the server, FORMCYCLE provides a monitoring bean for each server type. It can be accessed and read via JMX by using tools such as for example JConsole.

The beans are registered under the following names:

Frontend-Server

de.xima.fc:type=FSMonitor,qualifier=<contextName>

Master-Server

de.xima.fc:type=MSMonitor,qualifier=<contextName>

In addition, a monitoring bean with information about the installed applications is offered on both server types:

Version information

de.xima.fc:type=FCVersion,qualifier=<qualifier>

The qualifier is the context name of the applications. It is necessary for supporting parallel installations of FORMCYCLE on a server. By default, the context name is the name of FORMCYCLE's WAR file, but it can be changed by modifying the context name parameter XFC_CONTEXT_NAME within the web.xml.

When starting the server, the current context name is logged. You may need to modify the logging settings to see the name. There are different monitoring attributes available for each bean, which are listed below.

Overview of the settings for MSMonitor (master server)

Overview of the settings for FSMonitor (frontend server)

Overview of the settings for FCVersion (frontend server and master server)

JSON REST API

The JSON interface has been removed since version 6.0.0 in favor of a separate Jolokia installation. The beans used for monitoring are still available. The JSON interface of the monitoring allowed read-only access and could only be called via the application server (localhost/127.0.0.1). If this is wanted, the access would have to be configured within the Jolokia application, more information can be found here.

A possible call, after installation of Jolokia, looks like the following:

http://localhost/jolokia/read/de.xima.fc:type=MSMonitor,qualifier=formcycle

JSON response:

{
  "request": {
    "mbean": "de.xima.fc:qualifier=formcycle,type=MSMonitor",
    "type": "read"
  },
  "value": {
    "running": true,
    "failed_login_count": 0,
    "fs_active": {
      "localhost": true
    },
    "db_connected": true,
    "fs_connected_count": 1,
    "fs_connected": {
      "localhost": true
    },
    "fs_disconnected_count": 0,
    "fs_status": {
      "localhost": "CONNECTED"
    }
  },
  "timestamp": 1579186291,
  "status": 200
}

More information about the integration of the framework Jolokia and a more detailed documentation can be found here.

Nagios integration

The Nagios monitoring application may be used for reading and showing monitoring info as well by using the JSON REST API described above. This requires the Nagios plugin jmx4perl to be installed. A detailed installation instruction can be found on their website. This allows querying the JSON REST API with the corresponding commands.

Examples

These examples assume that Nagios is installed on the the same server as the FORMCYCLE application(s).

define command{
 command_name          check_jmx4perl
 command_line          check_jmx4perl --url $ARG1$ --mbean $ARG2$ --attribute $ARG3$ $ARG4$
}

define service{
 use                  generic-service
 host_name            localhost
 service_description  MS:FS-connected-count
 check_command        check_jmx4perl!http://localhost/formcycle/monitoring/!de.xima.fc:type=MSMonitor,qualifier=formcycle!fs_disconnected_count!--warning 1 --critical 2
}

define service{
 use                  generic-service
 host_name            localhost
 service_description  MS:DB-connected
 check_command        check_jmx4perl!http://localhost/formcycle/monitoring/!de.xima.fc:type=MSMonitor,qualifier=formcycle!db_connected!--string --critical 'false'
}

define service{
 use                  generic-service
 host_name            localhost
 service_description  MS:FS-localhost
 check_command        check_jmx4perl!http://localhost/formcycle/monitoring/!de.xima.fc:type=MSMonitor,qualifier=formcycle!fs_connected!--path=localhost --string --critical 'false'
}

define service{
 use                  generic-service
 host_name            localhost
 service_description  FS:connected
 check_command        check_jmx4perl!http://localhost/frontend-server/monitoring/!de.xima.fc:type=FSMonitor,qualifier=frontend-server!connected!--string --critical 'false'
}

Running Nagios on a different server

For security concerns, the JSON REST API does not allow querying the monitoring info from other IP addresses, only from the local server. Running Nagios on a different server and querying the monitoring info is still possible, but requires some additional setup.

One option is to setup the routing accordingly or using a proxy.

Another options for using Nagios on a different server is by providing certain options to the monitoring servlet. The parameter policyLocation provides the servlet with the URL to a Jolokia policy file, which will be passed on to Jolokia. The monitoring servlet is an extends Jolokia standard servlet and all Jolokia-specific parameters can be used. A list of relevant parameters can be found website.

A third option is running Jolokia in parallel to FORMCYCLE or the frontend server. Jolokia provides an application with a Java-EE agent for this purpose, documentation and download).

This agent does not possess any restrictions for read operations or control commands. However, as this represents a potential security issue, we strongly recommend to configure this agent for the server and network settings in use and restrict access as much as possible. For example, access should be restricted to the server running the Nagios application.

Jolokia provides more details on security-related options in their documentation.

When Jolokia is run parallel to FORMCYCLE, the connection to the frontend server localhost must be modified as follows:

define service{
 use                  generic-service
 host_name            fc-test
 service_description  MS:FS-localhost
 check_command        check_jmx4perl!http://fc-test/jolokia/!de.xima.fc:type=MSMonitor,qualifier=formcycle!fs_connected!--path=localhost --string --critical 'false'
}

Frontend server monitoring URL

7.1.0+  This feature is available since FORMCYCLE version 7.1.

You can also use the following URL to monitor the status of the frontend server (available only on the master server):

https://<domain>/<context>/monitor/fs/connection

Due to security concerns, this URL is disabled by default. To enable it, you need to configure the application properties monitoring.enabled and monitoring.allowed.hosts according to your needs.

For example, when the FORMCYCLE server can be reached via the domain demo.company.org via the context formcycle, the URL becomes https://demo.company.org/formcycle/monitor/fs/connection/.

To identify the frontend server, you must either specify the name of the system frontend server via the parameter name, or its internal database ID via the parameter id:

https://<domain>/<context>/monitor/fs/connection?name=MyFrontendServer
https://<domain>/<context>/monitor/fs/connection?id=5963

Then you can make use of the following monitoring options:

• https://<domain>/<context>/monitor/fs/connection?name=<Name>

Checks whether the given frontend server is connected to the master server. Returns the HTTP status code 200 if connected, and 500 otherwise.

• https://<domain>/<context>/monitor/fs/connection?name=<Name>&action=connect

Attempts to establish a connection to the given frontend server. When the frontend server is already connected to the master server, no action is taken. Returns the HTTP status code 200 if the frontend server was already connected to the master or when the connection could be established successfully. Otherwise, returns the status code 500 when the connection could not be established.

• https://<domain>/<context>/monitor/fs/connection?name=<Name>&action=connect&force=true
  
  

Attempts to establish a connection to the given frontend server. When the frontend server is already connected to the master server, cuts the connection and attempts to reconnect to the frontend server. Returns the HTTP status code 200 when the connection could be estabslished successfully, and 500 when the connection could not be establishe