Wiki source code of Monitoring

Show last authors
1 {{content/}}
2
3 == Available monitoring beans ==
4
5 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//.
6
7 The beans are registered under the following names:
8
9 ; Frontend-Server
10 : de.xima.fc:type=FSMonitor,qualifier=<contextName>
11 ; Master-Server
12 : de.xima.fc:type=MSMonitor,qualifier=<contextName>
13
14 The context name 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//.
15
16 When starting the server, the current context name is logged. You may need to modify the [[logging settings>>doc:.UserInterface.Logging]] to see the name. There are different monitoring attributes available for each bean, which are listed below.
17
18 {{table caption="Overview of the settings for MSMonitor (master server)" dataTypeAlpha="0" preSort="0-asc"}}
19 |=Key|=Description|=Possible options
20 |running|Whether the {{mserver/}} has been started successfully.|true, false
21 |db_connected|Whether the {{mserver/}} could establish a connection to the database.|true, false
22 |fs_connected|A map of the names of all {{fserver number="plural"/}} and whether they are connected to this master server|<serverName> : true, false
23 |fs_active|A map of the names of all {{fserver number="plural"/}} and whether this master server should attempt to establish a connection to that server automatically.|<serverName> : true, false
24 |fs_status|A map of the names of all {{fserver number="plural"/}} and the connection status of that server.|<serverName> : CONNECTED, NOT_CONNECTED, ERROR, RECONNECTING, DISCONNECTING , CONNECTING, AUTHENTICATING, WAIT_FOR_CONNECTION
25 |fs_disconnected_count|The number of {{fserver number="plural"/}} not connected to this {{mserver/}}|A non-negative number.
26 |fs_connected_count|The number of {{fserver number="plural"/}} connected to this {{mserver/}}|A non-negative number.
27 |failed_login_count|For each login name, the login cache contains how many times a user made a failed login attempt with that login name. This is the number of login names in that cache.|A non-negative number.
28 {{/table}}
29
30 {{table caption="Overview of the settings for FSMonitor (frontend server)" dataTypeAlpha="0" preSort="0-asc"}}
31 |=Key|=Description|=Possible options
32 |running|Whether the {{fserver/}} has been started successfully.|true, false
33 |connected|Whether this {{fserver/}} is connected to a {{mserver/}}.|true, false
34 |failed_login_count|For each login name, the login cache contains how many times a user made a failed login attempt with that login name. This is the number of login names in that cache.|A non-negative number.
35 |status|The connection status of this {{fserver/}}.|CONNECTED, NOT_CONNECTED, ERROR, RECONNECTING, DISCONNECTING, CONNECTING, AUTHENTICATING, WAIT_FOR_CONNECTION
36 {{/table}}
37
38 == JSON REST API ==
39
40 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>>https://jolokia.org/reference/html/security.html#d0e3128||rel="noopener noreferrer" target="_blank"]].
41
42 A possible call, after installation of Jolokia, looks like the following:
43
44 {{info}}
45 [[http:~~/~~/localhost/jolokia/read/de.xima.fc:type=MSMonitor,qualifier=formcycle>>http://localhost/jolokia/read/de.xima.fc:type=MSMonitor,qualifier=formcycle]]
46 {{/info}}
47
48 (% class="wikigeneratedid" id="HJSONresponse" %)
49 JSON response:
50
51 {{code language="JSON"}}
52 {
53 "request": {
54 "mbean": "de.xima.fc:qualifier=formcycle,type=MSMonitor",
55 "type": "read"
56 },
57 "value": {
58 "running": true,
59 "failed_login_count": 0,
60 "fs_active": {
61 "localhost": true
62 },
63 "db_connected": true,
64 "fs_connected_count": 1,
65 "fs_connected": {
66 "localhost": true
67 },
68 "fs_disconnected_count": 0,
69 "fs_status": {
70 "localhost": "CONNECTED"
71 }
72 },
73 "timestamp": 1579186291,
74 "status": 200
75 }
76 {{/code}}
77
78 (% class="wikigeneratedid" %)
79 More information about the integration of the framework [[Jolokia>>url:https://jolokia.org/||rel="__blank"]] and a more detailed documentation can be found [[here>>https://jolokia.org/reference/html/||rel="noopener noreferrer" target="_blank"]].
80
81 == Nagios integration ==
82
83 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>>url:http://search.cpan.org/~~roland/jmx4perl/||rel="__blank"]] to be installed. A detailed installation instruction can be found on [[their website>>url:https://jolokia.org/tutorial.html||rel="__blank"]]. This allows querying the JSON REST API with the corresponding commands.
84
85 === Examples ===
86
87 {{info}}
88 These examples assume that Nagios is installed on the the same server as the {{formcycle/}} application(s).
89 {{/info}}
90
91 {{panel title="Command" fullwidth="true" initial="hidden" triggerable="true"}}
92 {{code language="none"}}
93 define command{
94 command_name check_jmx4perl
95 command_line check_jmx4perl --url $ARG1$ --mbean $ARG2$ --attribute $ARG3$ $ARG4$
96 }
97 {{/code}}
98 {{/panel}}
99
100 {{panel title="Service definitions" fullwidth="true" initial="hidden" triggerable="true"}}
101 Querying the number of {{fserver number="plurar"/}} not connected to this {{mserver/}}. When there are any disconnected servers, a warning will be displayed. When there is more than one disconnected server, Nagios will treat this warning as critical.<br>
102 <br>
103 {{code language="none"}}
104 define service{
105 use generic-service
106 host_name localhost
107 service_description MS:FS-connected-count
108 check_command check_jmx4perl!http://localhost/formcycle/monitoring/!de.xima.fc:type=MSMonitor,qualifier=formcycle!fs_disconnected_count!--warning 1 --critical 2
109 }
110 {{/code}}
111 {{/panel}}
112
113 {{panel title="Querying the database connection status of the {{mserver/~}~}" fullwidth="true" initial="hidden" triggerable="true"}}
114 {{code language="none"}}
115 define service{
116 use generic-service
117 host_name localhost
118 service_description MS:DB-connected
119 check_command check_jmx4perl!http://localhost/formcycle/monitoring/!de.xima.fc:type=MSMonitor,qualifier=formcycle!db_connected!--string --critical 'false'
120 }
121 {{/code}}
122 {{/panel}}
123
124 {{panel title="Querying whether the {{fserver/~}~} localhost is connected to the {{mserver/~}~}" fullwidth="true" initial="hidden" triggerable="true"}}
125 {{code language="none"}}
126 define service{
127 use generic-service
128 host_name localhost
129 service_description MS:FS-localhost
130 check_command check_jmx4perl!http://localhost/formcycle/monitoring/!de.xima.fc:type=MSMonitor,qualifier=formcycle!fs_connected!--path=localhost --string --critical 'false'
131 }
132 {{/code}}
133 {{/panel}}
134
135 {{panel title="Querying the {{fserver/~}~} whether it is connected to a {{mserver/~}~}" fullwidth="true" initial="hidden" triggerable="true"}}
136 {{code language="none"}}
137 define service{
138 use generic-service
139 host_name localhost
140 service_description FS:connected
141 check_command check_jmx4perl!http://localhost/frontend-server/monitoring/!de.xima.fc:type=FSMonitor,qualifier=frontend-server!connected!--string --critical 'false'
142 }
143 {{/code}}
144 {{/panel}}
145
146 === Running Nagios on a different server ===
147
148 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.
149
150 One option is to setup the routing accordingly or using a proxy.
151
152 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>>url:https://jolokia.org/reference/html/agents.html#agent-war-init-params||rel="__blank"]].
153
154 A third option is running Jolokia in parallel to {{formcycle/}} or the {{fserver/}}. Jolokia provides an application with a Java-EE agent for this purpose, [[documentation>>url:https://jolokia.org/reference/html/agents.html#agents-war||rel="__blank"]] and [[download>>url:https://jolokia.org/download.html||rel="__blank"]]).
155
156 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.
157
158 Jolokia provides more details on security-related options [[in their documentation>>url:https://jolokia.org/reference/html/security.html||rel="__blank"]].
159
160 When Jolokia is run parallel to {{formcycle/}}, the connection to the {{fserver/}} //localhost// must be modified as follows:
161
162 {{code language="none"}}
163 define service{
164 use generic-service
165 host_name fc-test
166 service_description MS:FS-localhost
167 check_command check_jmx4perl!http://fc-test/jolokia/!de.xima.fc:type=MSMonitor,qualifier=formcycle!fs_connected!--path=localhost --string --critical 'false'
168 }
169 {{/code}}
170
171 == Frontend server monitoring URL ==
172
173 {{version major="7" minor="1" /}} This feature is available since {{formcycle/}} version 7.1.
174
175 You can also use the following URL to monitor the status of the frontend server (available only on the master server):
176
177 {{code language="text"}}
178 https://<domain>/<context>/monitor/fs/connection
179 {{/code}}
180
181 Due to security concerns, this URL is disabled by default. To enable it, you need to configure the [[application properties>>doc:Formcycle.SystemSettings.ConfigFiles.ApplicationProperties]] //monitoring.enabled// and //monitoring.allowed.hosts// according to your needs.
182
183 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//.
184
185 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//:
186
187 {{code language="text"}}
188 https://<domain>/<context>/monitor/fs/connection?name=MyFrontendServer
189 https://<domain>/<context>/monitor/fs/connection?id=5963
190 {{/code}}
191
192 Then you can make use of the following monitoring options:
193
194 * {{code language="plain"}}https://<domain>/<context>/monitor/fs/connection?name=<Name>{{/code}}
195
196 Checks whether the given frontend server is connected to the master server. Returns the HTTP status code //200// if connected, and //500// otherwise.
197
198 * {{code language="plain"}}https://<domain>/<context>/monitor/fs/connection?name=<Name>&action=connect{{/code}}
199
200 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.
201
202 * {{code language="plain"}}https://<domain>/<context>/monitor/fs/connection?name=<Name>&action=connect&force=true{{/code}}
203
204 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 established.