The WATCH facility is a powerful adjunct in server administration. From the administration menu it provides an online, real-time, in-browser-window view of request processing in the running server. The ability to observe live request processing on an ad hoc basis, without changing server configuration or shutting-down/restarting the server process, makes this facility a great configuration and problem resolution tool. It allows (amongst other uses)
A single client per server process can access the WATCH facility at any
one time. The report can be generated for a user-specified number of seconds
or aborted at any time using the browser's stop button.
13.1 - Event Categories
An event is considered any significant point for which the
server code has a reporting call provided. These have been selected to provide
maximum information with minimum clutter and impact on server performance.
Obvious examples are connection acceptance and closure, request path
resolution, error report generation, network reads and writes, etc. Events are
collected together into groupings to allow clearly defined areas of interest
to be selected for reporting. The report menu provides for the inclusion of
any combination of the following categories.
Request
By default all requests to all services are WATCHed. Fine control may be exercised over exactly which requests are reported, allowing only a selected portion of all requests being processed to be concentrated on, even on a live and busy server. This is done by filtering requests according the following criteria.
These filters are controlled using fully-specified or wildcarded strings. Requests that do not match the filter are not reported. In the case of originating client and destination service, requests are eliminated before ever appearing in the report. Path filtering is slightly different, requiring some request processing before the path can be determined. Depending on the categories selected this may result in some events begin displayed. It will be eliminated, with an accompanying explanatory message, as soon the path has been determined.
The following examples are grouped in the same order as the categories listed above; client, service and path.
alpha.wasd.dsto.defence.gov.au *.wasd.dsto.gov.au 131.185.250.202 131.185.250.* beta.wasd.dsto.defence.gov.au:8000 beta.wasd.dsto.defence.gov.au:* http://* https:* *:80 /ht_root/src/* /cgi-bin/* /web/*/cyrillic/*
The following example illustrates the format of the WATCH report. It begins with a six-line heading. The first two record the date, time and official server name, with underline. The third provides the WASD server version. The fourth and fifth provide a list of the categories being recorded and the filters in use. The sixth, the column headings described as follows:
Note that some items also include a block of data. The request header category does this, providing the blank-line terminated text comprising the HTTP header. Rule mapping also provides a block of information representing each rule as it is interpreted. Generally WATCH-generated information can be distinguished from other data by it's uniform format and delimiting vertical bars. Initiative and imagination is sometimes required to interpret the free-form data but a basic understanding of HTTP serving and a little consideration is generally all that is required to deduce the essentials of any report.
14-NOV-1998 20:47:41 WATCH REPORT gamma.wasd.dsto.defence.gov.au:80 --------------------------------------------------------------------- |HTTPd-WASD/5.3.0 OpenVMS/AXP Digital-TCPIP SSL| |Watching: connect, request, request header, mapping, response, response header (219)| |Client: "*" Service: "*" Path: "*"| |Time_______|Module__|Line|Item|Category|Event...| |20:47:43.46 NET 1035 0001 CONNECT ACCEPT 131.185.250.202,30214 http://gamma.wasd.dsto.defence.gov.au:80| |20:47:43.46 REQUEST 1171 0001 REQUEST HEADER 354 bytes| GET /ht_root/ HTTP/1.0 If-Modified-Since: Tuesday, 03-Nov-98 18:51:51 GMT; length=9904 Referer: http://gamma.wasd.dsto.defence.gov.au/ Connection: Keep-Alive User-Agent: Mozilla/3.03Gold (X11; I; OpenVMS V7.1-1H1 AlphaServer 4100 5/400 4MB) Pragma: no-cache Host: gamma.wasd.dsto.defence.gov.au Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */* |20:47:43.46 REQUEST 2144 0001 REQUEST GET /ht_root/| |20:47:43.46 MAPURL 0298 0001 MAPPING PATH /ht_root/| /ht_root/ .. REDIRECT /web/nt02/* http://nt02.wasd.dsto.defence.gov.au/ /ht_root/ YN PASS /* 403 Access denied. ![HO:131.185.250.* HO:131.185.247.*] /ht_root/ N. service [[gamma.wasd.dsto.defence.gov.au:8088]] /ht_root/ Y. service [[*]] /ht_root/ .. SET /web/* stmLF /ht_root/ .. SET /ht_root/* stmLF /ht_root/ .. SET /ht_root/src/* NOcache stmLF /ht_root/ .. MAP /httpd-internal-icons/* /httpd/-/* /ht_root/ .. PASS /ht_root/runtime/* /ht_root/runtime/* /ht_root/ .. PASS /*/-/* /ht_root/runtime/*/* /ht_root/ Y- PASS /ht_root/* |20:47:43.46 MAPURL 0321 0001 MAPPING RESULT /ht_root/ HT_ROOT:[000000] - -| |20:47:43.46 CACHE 0595 0001 RESPONSE CACHE HT_ROOT:[000000]HOME.HTML| |20:47:43.46 NET 1963 0001 RESPONSE HEADER 267 bytes| HTTP/1.0 200 Success Server: HTTPd-WASD/5.3.0 OpenVMS/AXP Digital-TCPIP SSL Date: Sat, 14 Nov 1998 10:17:43 GMT Last-Modified: Wed, 04 Nov 1998 04:21:51 GMT Content-Type: text/html; charset=ISO-8859-1 Content-Length: 9904 Connection: Keep-Alive Keep-Alive: |20:47:43.46 REQUEST 0450 0001 REQUEST STATUS 200 rx:354 tx:10171 bytes| |20:47:43.46 REQUEST 0252 0001 CONNECT KEEP-ALIVE 131.185.250.202,30214| |20:47:48.66 NET 1502 0001 CONNECT CLOSE 131.185.250.202,30214|
The following provides a brief explanation on the way WATCH operates and any usage implications.
A single client may be connected to the WATCH facility at any given time. When connecting the client is sent an HTTP response header and the WATCH report heading lines. The request then remains connected until the WATCH duration expires or the client overtly aborts the connection. During this period the browser behaves as if receiving a sometimes very slow, sometimes stalled, plain-text document. As the server processes WATCHable events the text generated is sent to the WATCH-connected client.
If the connection is aborted by the user some browsers will consider document retrieval to be incomplete and attempt to reconnect to the service if an attempt is made to print or save the resulting document. As the printing of WATCH information is often quite valuable during problem resolution this behaviour can result in loss of information and generally be quite annoying. Appropriate use of the duration selector when requesting a report can work around this, as at expiry the server disconnects, browsers generally interpreting this as legitimate end-of-document (when no content-length has been specified).
During report processing some browsers may not immediately update the on-screen information to reflect received data without some application activity. If scroll-bars are present on the document window manipulating either the horizonal or vertical slider will often accomplish this. Failing that minimizing then restoring the application will usually result in the most recent information being visible.
Browser reload/refresh may be used to restart the report. A browser will quite commonly attempt to remain at the current position in the document, which with a WATCH report's sustained but largely indeterminate data stream may take some time to reach. It is suggested the user ensure that any vertical scroll-bar is at the beginning of the current report, then refresh the report.
Selecting a large number of categories, those that generate copious output for a single event (e.g. response body) or collecting for extended periods can all result in the receipt of massive reports. Some browsers do not cope well with documents megabytes in size.
When supplying WATCH output as part of a problem report
please ZIP the file and include it an an e-mail attachment. Mailers often
mangle the report format making it difficult to interpret.
13.5 - Command-Line Use
Although intended primarily as a tool for online use WATCH can be deployed at server startup with a command-line qualifier and provide report output to the server process log. This is slightly more cumbersome than the Web interface but may still be useful in some circumstances. Full control over event categories and filters is possible.
The category integer must be the bitwise-OR of the constants found in the ADMIN.H source code header file. The end of the category list in the on-line WATCH report header contains a parenthesized integer. This is the number representing the enabled categories for that report and can be used for those same categories from the command line.
The following examples illustrate the command-line WATCH specification.
/NOWATCH /WATCH=88 /WATCH="88,*,*,/cgi-bin/*"