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.
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.
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
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:
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.
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
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.
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
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
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>
PS: This is an automated message, please do not respond!
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.