WATCH  provides an online, real-time, in-browser-window view of
━━━━━  request processing in the running server, without changing
       configuration or restarting the server process.

A useful configuration and problem investigation tool, WATCH (yes, always
capitalised - if only to make it identifiable as a tool, not a verb) allows
assessment of mapping and authorisation rules, observation of general and
problematic request processing, including script interactions, network I/O,
along with detailed observation of server behaviour.

Also see 'Notes' below and attached image.

Overview
--------
WATCH is accessed via the Server Admin facility

  https://wasd.vsm.com.au/wasd_root/wasdoc/features/admin.png

and must be subject to authorisation.  A single client per server can use the
WATCH facility at any one time.  WATCH is available in one of three modes.

1) As a one-shot, one-off WATCH of a particular request, available from the
Request Report page of the Server Admin facility.

2) All new requests being processed are candidates for being WATCHed.
Categories are selected before initiating the WATCH and the report can be
generated for a specified duration or cancelled using the browser stop
button.

3) As a triggered WATCH session where network read (Rx) and write (Tx) data
are searched for a pattern which when hit activates the specified WATCH
session items.

The WATCH report can be targeted at the client browser, browser plus log
file, or log file only (as a detached approach to WATCHing).

Event Categories
----------------
The WATCH report menu provides for selectors under various headings.

Request Processing - each major step in processing a request
```````     Header - the HTTP request header
              Body - with a POST or PUT the content is provided as a
                     hexadecimal dump on the left and printable
                     characters rendered on the right

Response Processing - each major step in generating a response
````````     Header - the HTTP response header
               Body - most (not all) requests generate content, provided
                      as hexadecimal dump on the left and printable
                      characters rendered on the right

General Connection - each TCP/IP connection acceptance and closure
```````    Mapping - provides multiple lines indicating the path to be
                     mapped, whether it was matched, and finally the
                     derivative path, VMS file specification, any script
                     name and specification resolved
     Authorization - when authorization is deployed this category shows
                     the rules examined to determine if a path is
                     controlled, any authentication events in assessing
                     username and password, and user and request
                     capabilities (read and/or write) for that path
             Error - essential elements of a request error and may include
                     a VMS status value and associated system message
               CGI - provides generated CGI variable names and values
                     as used by scripting and SSI documents as well as
                     processing the response header returned by scripts
               DCL - scripting process management and input/output streams 
                     (SYS$INPUT, SYS$OUTPUT, SYS$COMMAND, CGIPLUSIN)
            WebDAV - specific processing points and meta-data XML

Network Activity - each raw network read and write the VMS status and
```````            size of the I/O
            Data - each raw network read or write the content is provided
                   as a hexadecimal dump on the left and with printable
                   characters rendered on the right
          HTTP/2 - detailed overview of the underlying HTTP/2 framing and
                   connection management exchanges of client and server 
           Proxy - each major step with proxy tunnelling 
             SSL - provides an indication of high-level TLS activity
                   if also reporting network data the cipher-text bytes
                   are displayed with plain-text rendered on the right 

Other Logging - access logging events include log open, close and flush,
`````           as well as request entries
       DECnet - reports on all processing steps and input/output streams
        Match - significant detail during string matching activities
       Script – sets CGI variable WATCH_SCRIPT allowing a script to
                output specific debugging data when being WATCHed
     Internal - information on other significant internal server processing 

Filters
-------
Filters are generally wildcard strings matching the various elements.

    Protocol - the HTTP protocol being used to transport the request
      Client - originating host name (if lookup is enabled) or address
               in dotted-decimal notation, with the [x]moi checkbox
               filtering on the WATCHing client's host address
     Service - includes the scheme of the service (i.e. "http:", "https:"),
               the host name (real or virtual), and the port
     Request - This filter operates on the entire HTTP request header with
               all fields supplied available to be filtered against **
         URI - the string specifying the requested resource including the
               resource path along with any query string **
Realm & User - filters request authentication information
 HTTP Status - allows a class of response status e.g. 1 (informational),
               2 (success), 3 (redirection), 4 (client error) and
               5 (server error) or a specific response status (e.g. 404) 
               (often very late in the request-response cycle)
     Trigger - pattern of bytes in the network Rx or Tx stream **
               unlike other filters this a not a wildcard string, is case-
               sensitive, and add significant overhead to WATCH processing

  ** URL-encoding allows for non-printing characters

Report Format
-------------
This example shows a report providing items, "connect, request, req-header,
response, error (539) via HTTP/2 for 60 seconds (plus log)".  The columns,
"Time", code "Module", code "Line", counted "Item", selected "Category" and
"Event" designate fixed fields, with other lines associated free-form text.
Long lines have been '↵' wrapped.

  |Time_______|Module__|Line|Item__|Category__|Event...|
  |13:37:07.58 HTTP2REQ 0271 005006 CONNECT    HTTP/2 begin 5 with gort.lan,53200|
  |++++++++++++++++++++++++++++++++++++++++++++
  |13:37:07.59 HTTP2REQ 0287 005006 REQ-HEADER HEADER 444 bytes|
  GET /httpd/-/admin/ HTTP/1.1
  accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
  sec-fetch-site: none
  sec-fetch-dest: document
  accept-encoding: gzip, deflate, br
  sec-fetch-mode: navigate
  user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15
  ↵(KHTML, like Gecko) Version/17.6 Safari/605.1.15
  authorization: Basic ************************
  accept-language: en-AU,en;q=0.9
  host: x86vms.lan
  
  |13:37:07.59 REQUEST  3773 005006 REQ-HEADER DATA|
  ENTRY 001 [012] $ {12}request_line={28}GET /httpd/-/admin/ HTTP/1.1
  ENTRY 002 [014] > {6}accept={63}text/html,application/xhtml+xml,application/xml;
  ↵q=0.9,*/*;q=0.8
  ENTRY 003 .014. > {14}sec-fetch-site={4}none
  ENTRY 004 [017] > {14}sec-fetch-dest={8}document
  ENTRY 005 [018] > {15}accept-encoding={17}gzip, deflate, br
  ENTRY 006 [022] > {14}sec-fetch-mode={8}navigate
  ENTRY 007 .001. > {10}user-agent={117}Mozilla/5.0 (Macintosh; Intel Mac OS
  ↵X10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.6 Safari/605.1.15
  ENTRY 008 [031] > {13}authorization={30}Basic ************************
  ENTRY 009 [007] > {15}accept-language={14}en-AU,en;q=0.9
  ENTRY 010 [024] > {4}host={10}x86vms.lan
  |13:37:07.60 SERVICE  1800 005006 CONNECT    UNKNOWN service|
  |13:37:07.60 REQUEST  4492 005006 REQUEST    GET /httpd/-/admin/|
  |13:37:07.61 ADMIN    0273 005006 RESPONSE   ADMIN /httpd/-/admin/|
  |13:37:07.62 REQUEST  1432 005006 REQUEST    STATUS 200 (OK) rx:54 tx:24025 bytes
  ↵40.0ms 601,981 B/s|
  |--------------------------------------------
  |13:37:07.62 HTTP2REQ 1170 005006 CONNECT    HTTP/2 end 5 with gort.lan,53200|
  |13:37:51.82 end|

Notes
-----
This article describes *not* the current items (v12.3) but future (v12.4?)
items.  WATCH behaviour remains the same though.  With proxy caching
obsoleted in v12.0 and further proxy functionality progressively removed,
v12.3 was left with tunnels and SOCKS5.  I suddenly realised most of the
WATCH proxy items no longer existed.  Previously more extensive proxy WATCH
has been reduced to a single item.

Excellent if all this seems somewhat familiar, it was distilled from current
WATCH documentation (ignore proxy descriptions) found at

  https://wasd.vsm.com.au/wasd_root/wasdoc/features/features010.h...

A v12.n persistent issue with WATCH made terminating a WATCH request
sometimes problematic.  The browser often continued to maintain a WATCH
connection.  This has been fixed (finally) with the forthcoming v12.4.  If
this issue is driving you spare drop me a line and I'll supply an interim
release.

This item is one of a collection at
https://wasd.vsm.com.au/other/#occasional