jWebSocket Watchdog Application User Guide

jWebSocket Watchdog is an application as its name implies, aiming at monitoring and controlling if a certain service or a group of them are properly running. At this state of documentation the jWebSocket Watchdog supports a monitoring test to control whether on certain host a certain TCP port is open. However, any kind of other tests can be added due to its flexible architecture.
The implemented TCP test verifies if on a certain host (identified by hostname or IP-Number) a certain service (identified by its port) is reachable. "Reachable" means that a simple TCP socket connection successfully can be established. No particular protocol, handshake or data communication needs to be implemented. jWebSocket Watchdog supports also notifications that in case of a failure are sent to a group of subscribers by Email or by the Application logs (for authenticated users). The tests can be configured using one or multiple scheduler services that define how and when the tests will be executed.
The jWebSocket Watchdog Application is a complete integration of the previous mentioned concepts in a Web Application running JavaScript as client side language (Web Browser client) and Java in the server side. The communication between the server and the client happens by means of the WebSocket protocol, so all connected clients can be notified in real time in case of a failure of a certain test through the application.
Installing Watchdog Application
The jWebSocket Watchdog application is released with the main configuration file: JWEBSOCKET_EE_HOME/conf/WatchdogPlugInEE/watchdog.xml which contains the main configuration needed to start jWebSocketServer and execute the Watchdog as one of the jWebSocket Plug-ins.
System Requirements
The following are the minimum server and client requirements for jWebSocket Watchdog.
Minimum Server Requirements
The following are the minimum server requirements:
  • The Java Virtual Machine and Java Development Kit (Oracle/Sun JDK | OpenJDK) 1.6 version or higher installed.
  • A Web server (e.g. Apache) installed to publish the Web application(s). 
  • The server may be a machine should be at least equipped with a Dual-Core processors or higher and at least with to 2 or more GByte of RAM. 
  • Depending on the applications particular process requirements and target multi-user concurrency, production servers may use Quad-Core processors and 8 GB or more of RAM dedicated to the JVM process running the jWebSocket server. 
  • For high speed database access on high user concurrency scenarios, the Watchdog database is recommended to be operated on dedicated servers to avoid overloads in the application server. 
Minimum Client Requirements

To use the jWebSocket Watchdog you must have network access to the server that runs the application and use any of the browsers that support the WebSocket communication protocol. Some of them are Google Chrome 4+, Safari 5+, Mozilla Firefox 8+, Opera 11+ and Internet Explorer 10+.

Watchdog Application User Interface
For the design of the Watchdog Application the JavaScript Framework ExtJS version 5.1.0 was used, which offers a broad amount of components, containers, layouts and reusable interfaces that can be easily created with a simple configuration object.
UI Structure
The Watchdog user interface is simple and easy to understand, basically the UI is divided in 5 main parts like shown in the sketch below:

 Figure 1: Watchdog Application user interface structure

Brief explanation of the content shown in each area:
  • Logo and header Area: Basically this area only shows the name of the application, the logo and the information of the authenticated user and the status of the connection on the right side of the header.
  • Subscribers Area: Contains the list of subscribers and the respective create/modify/refresh/delete actions to be applied to the subscribers.
  • Tests Area: This is the main area of the application, here is where the tests are listed and where selected tests can be modified or deleted. The user has the possibility to create new tests, and manage the subscribers and the type of subscriptions per test.
  • Schedule Area: The Schedules Area gets ensabled because as asson as a test is selected selected test, a schedule is always related to a certain test. Each test can have one or more scshedules. In this way the user can program when he wants a specific test to be performed, e.g. two times a day or every 10 seconds if needed.
    The Schedule Area is separated in two sections:
    • Schedules: Containing the schedules in which will be ran a test.
    • Subscriptions: Containing the subscriptors that will be notified in case that the test fails and what kind of notification they will receive.
  • Test Execution Logs Area: In this area the administrator can see the current status of the Test executor on the server side. Notifications of the test execution status are broadcasted to all connected administrators in real time in order to control what is happening within the test executor thread on the server side.

 Figure 2: Watchdog User Interface rendered on Chrome Browser
Login and Security
When the user accesses the Watchdog application the first time, a login window will pop-up to the user requesting to enter his credentials. Once he clicks submit, the client will attempt to authenticate against the server.
 Figure 3: Login Window to access Watchdog
Once the user has been properly authenticated, the main dashboard will load the subscribers and the tests grids, allowing to the user to see if there are already created tests or subscribers. The login details area in the header of the page will also be updated with the authenticated user information as can be seen in the Figure 4.
Important:Advanced users may remove this window using the browser developer tools (DOM Inspector), however, the security of the complete Application is controlled from the server side, so even if a user avoids showing the Login Window they will still have no access to any functionality.

Figure 4: Header area containing the login information for the authenticated user
The header is composed by the Application Logo, the name of the application and the login information in the following format <connection status> | <username>@<client-id> Logout Button.
Non authenticated or non authorized users will get the following error upon trying to execute not allowed functionalities:
Figure 5: Access denied message shown to the users who don't have access
The current jWebSocket Watchdog application considers registered users, also other user than the administrator to be notified, for example with an email when a certain test fails. The subscribers panel is just to maintain the subscribers, it does not link subscribers and tests. This function will be explained below in the Tests chapter.
The Figure 6 below represents the Subscribers Area within the Watchdog Application:

 Figure 6: Subscribers area
This area contains all the information related to the subscribers, it is separated in 3 parts, the Actions Toolbar, the Subscribers List Grid and the Paging Plug-in to show the results grouped by pages.

Modify Subscriber

Upon double clicking on the subscriber grid items or just clicking the "Edit" button from the Actions Toolbar, the user can modify the current selected Subscriber Figure 7.

 Figure 7: Modifying a subscriber

Delete Subscriber

For security reasons the delete actions always prompts the user: Are you sure that you want to delete, yes or no. Non allowed users will not be able to run this action unless they have the specific right for that, the permissions are validated in both, the client and the server.

Add Subscriber

This action can be accessed by clicking on the Add button from the Actions Toolbar. Only Administrators will be allowed to add new subscribers. To successfully add a subscriber the user just needs to fill in properly each field shown in the Figure 8 below.

 Figure 8: Add subscriber window
Tests Area
The Tests area is composed of a toolbar with the main actions applicable for a test. A grid which shows the list of generic tasks that are currently stored in the server database. Per each test the Watchdog UI shows the following information: Name, Description, Timeout, Test Type, Success Executions, Failed Executions, etc.

Figure 9: Tests Area

Actions Toolbar

The following Toolbar Area is located below the header of the Tests Area wrapping the functionalities that can be applied to a certain test. See Figure 10.

 Figure 10: Tests Actions Toolbar

Creating a new TCP Test

As of May 2015 the Watchdog only supports TCP tests, which can be accessed by clicking in the New button on the Tests toolbar area, "New TCP Test".

 Figure 11: New TCP Test Button
Then a new Create TCP Test window will appear on the screen (Figure 12).

Figure 12: Creating a TCP Test
The fields of a certain test varies depending on its type and what is required for each test. However, for the TCP Test it is required to provide a Name for the test, an Execution Timeout (The timeout in which the test should show a result "in milliseconds"), the host that will be tested, for example, localhost, the port to check and a few more parameter explained below:

Test Name: Any name for your test.
Description: The description of the test.
Possible Causes: The causes that could have originated the test to fail.
Resolve Options: How to solve this problem in case that someone receives a message with the failure notification.
Timeout: Time to wait until the test fails.
Test Type: The type of the test, only one supported right now TCP.
Host: Host that you want to test, e.g. localhost.
Port: Port that you want to test e.g. 8084.

Min data length: The minimum amount of bytes to wait from the target server, if the bytes received are less than the amount here established, then the test is considered as a failure.

Failure repeat changes: How many times the test can fail until we send a notification.

Failure delay in seconds: How many seconds the failure can be delayed.

Wait for target data: If enabled, then that means that the test must wait until the target returns some data.

Please consider that in some environments hostnames cannot be resolved due to DNS configuration. Please in these cases use the IP number to access the desired host.

Modifying a Test

To modify a test simply select a test and then click the "Edit" button from the Test Actions Toolbar on Figure 10, the same window used to add the test will be generated, but this time populated with the information of the Test the user selected, so he can easily change the values. Please note that if you change the Port or the Host, the test will immediately will uses these new settings and perform according to its schedule.

Managing Test Subscriptions

You may have wondered, how the Watchdog handles the subscriptions for a certain Test to notify a user or a group of them when a test fails? This is very simple, by selecting a test from the list, then you can just check on the bottom right side of the application, the Subscriptions area as Figure 13 below.
 Figure 13: Manage Subscriptions Area
This UI section will simply allow us to manage which user/s will be notified when the selected test fails and what kind of notifications we want to use to let the user know that something went wrong with a certain test on the server. The biggest advantage is that the server administrator doesn't have to worry about if his server is down or some service is not working properly, he simply specifies a test to send him a mail or an SMS (Coming soon...) so he can check what happened with his server.
The list of existing subscriptions: Contains all subscribed users and type of notifications to be used to broadcast a message when the selected test fails the execution progress.
To create an existing subscription just click on the "Add" button from the subscription area, or edit existing ones by clicking edit button. Once the add button is clicked, the following window will appear:

Where the Select subscriber contains the list of existing subscribers and the type of subscriptions right now supported as mentioned before are Email and Application (Using the logger output area).

Test failure notification per Email

When a test fails, a notification message will be sent to all subscribed users in the following format:


WATCHDOG: Test 'Nginx' execution has FAILED!
Unfortunately we notify you that the execution of the test '<TEST_NAME>', performed on date/time 'Thu May 14 23:33:59 CEST 2015' FAILED with the following error message:< TEST_ERROR>.

You have been contacted because the Watchdog administrator has defined you as a subscriber of the test.

Please take all appropriate actions to solve the problem urgently.

Test description: <TEST_DESCRIPTION>

Best Regards,

Watchdog Admin.

PS: This is an automated message, please do not respond! 
Schedules Area
The Schedules are used to specify when and how a test will be executed, please see Figure 14 for more details.
Every time the user selects a certain test, the Schedules window is updated showing the Schedules information related to this test, for example, at what time a certain test will run.
 Figure 14: List of current schedules for the task "Apache Server running in Localhost"

Adding a Schedule for a selected Test

Once the user selects a test, the Schedule Area will be enabled, so he can add or edit schedules to that test. To add a certain Schedule the user will enter some data after clicking the Add button from the Schedules area, the following window will appear:
Start date: A dropdown calendar will be shown to the user, so he can simply pick the date on which he wants the executor to start running the test.
Start Time: This is a simple dropdown with a couple of time ranges, so the user can select or type at what time he wants the test to start.
Repeat interval: Indicates the interval in which the test will be executed, you can choose once a day, one time per month, etc...
Time Unit: Another dropdown which will allow you to pick the type of unit to be used combined with the interval to specify when the task will run.
End date and End Time are not required fields, so, the user can leave them empty, these fields specify when the executor will stop running a certain test. This is appropriate if a test should only run for a certain time frame.
Once the user entered all the parameters correctly he can click the Add button below the input fields and the schedule is added to the Schedules List shown in the bottom part of the Schedules Area.

Modify a Schedule

The Schedule can be modified by selecting a schedule in the list, automatically the upper form will be populated with the schedule information, so he can directly update it in a blink. Please see Figure 15 for more details.
Figure 15: Modifying a Schedule from the list
Watchdog Executor Logs
Contains all the logs generated by the server upon the test started and of course, the execution result, for example:

Figure 16: Watch Executor logs
The Log Executor function also supports two internal functionalities:
Clear Logs: Used to remove all the logs from the current window

Select All: Automatically selects the comment and allows the user to press control + C if needed.


Figure 17: On the menu the options to be applied upon RMB over the logs window
The Watchdog Application is another successful client/server side Real-Time communication application created on top of jWebSocket Framework. It allows to the final user to not only monitor existing hosts/ports, but also any other kind of services that can be monitored within a production environment. The Watchdog Application has a very flexible architecture allowing to users to create any kind of specific tests by simply providing a client interface and a server implementation which can be switched on with a simple configuration, allowing the Watchdog to be extensible, scalable and reusable among our Enterprise Edition Community users.
With this Application once again jWebSocket Framework proved its power to create highly customizable and with a very high performance WebSocket Applications in just a matter of days.

Copyright © 2013 Innotrade GmbH. All rights reserved.