Managing and Monitoring the Web Gateway
This page describes how to manage and monitor the InterSystems Web Gateway via the Web Gateway management pages.
Checking System Status
The System Status option displays the status of all active connections. You must be a system manager to use this feature. In each of the tables below, click a column head to sort by that column.
Connections to InterSystems IRIS
The first status table (Connections to InterSystems IRIS) displays information on connections to InterSystems IRIS®.
Item | Function |
---|---|
Connection Number | Number that the Web Gateway assigns to the connection. Your InterSystems IRIS license determines the number of possible connections. |
Gateway PID | The Web Gateway (or hosting web server) process ID for the connection. |
Server Name | Name of the InterSystems IRIS system connected to. Mirror members show current configuration name with mirror member name appended. |
InterSystems IRIS PID | Process ID on the InterSystems IRIS server. |
Status | Indicates whether information is being sent to or from the InterSystems IRIS system, as follows: Free — no information is being sent and the connection is ready to process the next request. In Use — information is being transmitted through the connection. Private — the connection is state-aware (preserve mode 1) and not free for general use. Server — the connection is being used by the InterSystems IRIS server. |
Idle time/Timeout | Indicates the amount of time that the connection has been idle against the timeout applied to that connection. The timeout is the ‘No Activity Timeout’ for connections in the state-less pool and the ‘Application timeout’ for connections marked as ‘Private’ (state-aware). |
Activity | Number of transactions (hits) the connection has processed. |
Interrupt | For a connection with status ‘In Use’, an Interrupt button will attempt to interrupt the corresponding InterSystems IRIS process and return it to the state where it is ready to accept the next web request. |
Close | If available, allows you to forcefully close down the connection by selecting it. See Closing Connections Manually. |
InterSystems IRIS Servers Table
The second status table (InterSystems IRIS Servers) displays information on InterSystems IRIS servers.
Item | Function |
---|---|
Server Number | The number that the Web Gateway assigns to the server. |
Server Name | Name of the InterSystems IRIS system connected to. |
Mirror Member | For mirror-aware configurations, the name of the mirror member. |
Mirror Status | For mirror-aware configurations, the name of the mirror configuration along with the mirror status of the server. The member type, Failover or Async, will be shown and the Primary will be labeled as 'Primary'. |
Total Connections | Number of connections to the InterSystems IRIS system. |
Connections In-Use | Number of connections that are currently in use (actively serving a Web request). |
Private Connections | Number of connections that are currently in use as state-aware sessions (preserve mode 1). |
Total Activity | Number of transactions (hits) the InterSystems IRIS system has processed. |
Queued Requests | Number of Web requests that are held in a queue waiting for a free connection to the InterSystems IRIS system. Queued requests are an indication that the InterSystems IRIS license should be increased in order to maintain good performance. |
Close | Close all connections on this InterSystems IRIS server. See Closing Connections Manually. |
Application Paths Table
The third status table displays information for application paths.
Item | Function |
---|---|
Path Number | The number that the Web Gateway assigns to the application path. |
Path | The application path. |
Server Number | The number that the Web Gateway assigns to the InterSystems IRIS server. |
Server Name | The name of the InterSystems IRIS system connected to. |
Activity | The number of requests processed by this server for this path since the last Gateway. |
Status | The status for this server, one of Disabled, Enabled or Offline. Also the current master (or primary) server in the set is indicated in this column. |
Action | If a server is marked as Offline, this column contains a button allowing Administrators to mark it Online/Enabled again. |
Web Gateway Cache Table
The fourth status table lists the forms held in the Web Gateway response cache.
Item | Function |
---|---|
Cached Forms |
Name (including path) of cached form. |
Cached Data (Bytes) |
Amount of cached form data held in the Gateway (in Bytes). |
Cache Blocks In Use |
Total number of cache memory blocks in use. |
Cache File |
Name of physical file if permanent storage (on the web server host) is used to cache the file. |
Cache Form Activity |
Total number of times this form has been requested from the cache. |
Clear |
Clear this form from the cache. See Clearing the Cache. |
Closing Connections Manually
If your InterSystems IRIS system shuts down while a CSP connection is still active, CSP continues to try to connect to the system until one of the following occurs:
-
It successfully reconnects to the system.
-
CSP is shut down.
-
The connection is manually closed.
If your InterSystems IRIS system is scheduled for extensive downtime, you may want to close the connections. You can close sessions manually using the Close button on the System Status page.
Note that you can close the connections while the InterSystems IRIS system is down.
Clearing the Cache
Under certain circumstances, such as during the development process for web applications, it may be necessary to clear the Web Gateway cache. To do this:
-
From the Management Portal, navigate to System Administration > Configuration > Web Gateway Management and select System Status.
-
On the System Status page, there are a number of tables. To clear the cache, in the Cached Forms table, select the button in the Clear column (the right-most column) and the Total row (the bottom row). If the System Status page does not display a Cached Forms table, then there is no currently cached content. This may be because the cache has been cleared recently and nothing has been cached since then.
This action clears all cached content for the Web Gateway and removes the Cached Forms table from the page until there is new cached content.
Testing Server Connections
The Test Server Connection option is useful to test Web Gateway connectivity to your InterSystems IRIS systems. Note that you must be a system manager to use this feature.
To test CSP connectivity:
-
From the Web Gateway management pages main menu, select Test Server Connection.
-
Select the desired InterSystems IRIS system from the displayed list.
-
Select Connect.
Depending on your selection and the state of the server connection, you receive one of the following results:
Result | Meaning |
---|---|
CSP Test Form | The Web Gateway is working correctly and is able to connect to InterSystems IRIS. The form shows the basic parameters returned by the target InterSystems IRIS server (version and process ID). |
Server Availability Error | This error occurs any time that InterSystems IRIS is unreachable. If there are no additional error messages, check to ensure your InterSystems IRIS system is running. Also, check the Web Gateway Event Log for specific connectivity error messages. |
In all cases where an error condition is returned, check the Web Gateway Event Log for additional and more specific error information. Consider raising the log level to capture even more diagnostic information where necessary.
Viewing the Event Log
Use the View Event Log option from the Web Gateway management pages main menu to read the contents of the Web Gateway Event Log. The Event Log Level parameter determines what information is logged.
The Web Gateway stores the event log in a log file, named CSP.log by default. For convenience, the Web Gateway’s About Web Gateway management page indicates the location of this file. When the active log file reaches its capacity as specified by Event Log Rotation Size, it is copied to filename.old, where filename is the full original filename. If Event Log Rotation Size is blank (the default), the file grows until manually cleared. To save all logs in files named with date and time, select Retain All Log Files on the Default Parameters page. Each log entry is marked with a header record which captures the date, time and additional information with respect to the context in which the log entry was made.
Log entries follow the same machine-readable format which an InterSystems IRIS instance uses for its structured logging feature. This means you can use the same third-party tools to analyze the Web Gateway Event Log which you use to analyze the logs for your InterSystems IRIS instances. For added efficiency, the Web Gateway Event Log uses several of the same field names which other structured logs use: when, level, event, pid, and text. On the View Event Log page, the text and details fields are presented without their field names. However, the log entries available in the CSP.log file fully subscribe to the name-value pair (NVP) format.
What follows is an example of a Web Gateway Event Log entry as it appears in CSP.log. Each entry in CSP.log occupies one line. However, for readability this example is divided up onto multiple lines (marked by the \ character).
local-time="Thu Jul 21 11:39:20 2022" \ wg-build="RT 2202.1825 (win32/apapi:srv=2.4.52/apr=1.7.0/apu=1.6.1/mpm=WinNT)" \ wg-log-level=0 when="2022-07-21 15:39:20.831" level=WARNING event=WebGateway.SessionOpen \ pid=17216 thread-id=2072 text="Warning" \ details="A Connection between the Web Gateway and InterSystems IRIS has been found to be \ closed (possibly as a result of an intermediary, such as a firewall, timing-out the TCP session)"
Select Clear Log to clear all current entries from the Event Log.
The Log can be displayed in either ascending date/time order (the default) or descending date/time order. Select the link at the top right-hand corner of the form to reverse the display order. This link acts as a toggle between the two modes.
Finally, most browsers are unable to render more than about 1MB of log data in a single form. Therefore, as the volume of log data returned approaches 1MB, the Web Gateway terminates the display and prompts for the next page of data. See the More link at the bottom left-hand corner of the form. Additionally, a Top link is provided at the bottom right-hand corner of the form to allow you to quickly go back to the first form in the series.
Using the HTTP Trace Facility
The HTTP trace facility is accessed via the View HTTP Trace option.
The trace window consists of two main frames. The left-hand frame contains a list of HTTP requests processed by the Web Gateway by time and a unique request ID (assigned by the Web Gateway). As each request is selected, the request and response data is shown in the right-hand frame. Links allow easy navigation between the request and response message.
Note that the HTTP request headers reported by the Web Gateway are reconstituted because the hosting web server always assumes responsibility for parsing the request headers. The Web Gateway reassembles the complete header from the CGI environment variables supplied by the web server. However, if a request is passed directly through the NSD component (that is, effectively bypassing the web server), then the request header recorded is byte-for-byte the same as it was when dispatched from the client.