à la mode

Version 12.0.b, 22nd April 2022

Copyright © 2015-2022 Mark G. Daniel
Licensed under the Apache License, Version 2.0 (the "License");
https://www.apache.org/licenses/LICENSE-2.0
Software distributed under the License is on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

Contents



à la mode  (pronounced "ah-la-mode")  is a browser-based WASD Web server monitor with a sufficiently small resource footprint** not to impact server or system performance. à la mode is intended as a general tool for server behaviour and throughput observation, not for request or behaviour analysis. That is the purpose of tools such as WATCH. While à la mode can be used for checking counters and request activity on sites with any level of traffic, the graphs are more impressive when observing medium to busy sites. ** YMMV with platform and selected items but on an AlphaServer DS20E and HP rx2660 significantly less than 0.001 of a CPU.

à la mode provides textual and graphical data showing

Versions of à la mode are available for use with WASD v10.4.0 and later, and should work with all relatively modern browsers. Developed against Chrome, Firefox, MS Edge (10+), and Safari, on macOS (OS X) and Windows platforms, it uses HTML5 elements including SVG for graphing and will not work with the HTML4 generation of browsers.

Etymology:  WASD has produced a Spanish sounding application (Monitor de Sistema), so why not one with a French flavour? Although rather than meaning "fashionable" (which cannot be said of VMS or WASD), this application's name is intended to be reminscent of the North American usage, "on the top or side of" (in the sense that it's not an integral part of the WASD package). Not being much of a dessert person I might even prefer the cookery usage of "meats braised with vegetables in wine" but that's too much of a stretch :-)  Whatever the force-fit it seemed less prosaic than "WASDmon".

Usage

à la mode is activated by accessing the URL for its script location. This is usually something like (and may well open à la mode on this system)
http://the.site.name/cgiplus-bin/alamode
opening an in-line monitor, though can be a
a bookmarklet
opening a stand-alone window.

à la mode opens displaying the textual system and server information at the top left and system resource and server instantaneous utilisation bar graphs at the top right, seen on the image below. Basic system resources monitored are CPU, buffered I/O, disk (FCP) and network interface (NI), while server utilisation metrics include per-second file, script, proxy, WebDAV, and other requests, current number of connections and of those processing, responses OK (e.g. 200s) and not OK (e.g. 500s). Checkboxes below the system information allow various aspects to be toggled on/off. Sections open revealing additional information, and close hiding that information again. Values in graphs are adjusted to meaningful units, and maxima, if not fixed, represent values of the last five, or fifteen, minutes. Checkboxes activate the described functionality. Server directives (/DO=) will be displayed in blue and alerts in red immediately below the block of textual information, and can be cleared by clicking over them. Alerts include server (re)starts, script hard limits being reached, excessive 403 and 5nn responses, and other messages. Tooltips are provided for all major elements of the report.

 (left) Adjacent to the node name, the checkbox minimises the per-node display. When unchecked, the node name, host name, VMS time, processing synopsis, and any recent alert, are displayed in place of the full display.
Click and hold to enlarge ... or ... alamode.png

(Safari 11 on macOS, showing standalone à la mode)

disables data collection, closing the connection to the data source script.
disables data update but continues to collect and store data. Pausing the update allows a specific report to be examined without disturbance. Re-checking the box updates the display from the point it was disabled.
disable in the case of excessive alerting.
pop-up tooltips.
opens the line graphs seen at the lower half of the image. These provide five, or fifteen, minute summaries of the instantaneous system data shown in the bar graphs. Appropriate graphs contain an average. Some display a ↷ character following the label indicating additional or alternate data may be displayed by clicking on the graph.

expands data collection and the history graphs from 5 to 15 minutes. The complementary checkbox returns to a 5 minute history display but continues to collect over 15 minutes.
displays tabular data showing counts and percentages of total for all HTTP methods (e.g. GET, HEAD) and major server processing modules (e.g. DCL, Proxy).
display the server processes (and multiple instances if used) bar graphs showing process status and quota usage.
display additional tabular data on DCL and DECnet scripting, as well as history graphs for DECnet scripting, DCL process creation and deletion, and CGIplus/RTE (persistent-process) scripting.
displays tabular proxy processing data.
provides the last request's essential data including time, status, network totals, duration, client domain name (IP address), service connected to and request made.
displays the (instance) status report.
displays tabular WebDAV processing data.

Query String

Each of the above checkboxes may be checked or unchecked using appropriate elements of the request query string. The following keywords can each be checked with a =1 or =X, and unchecked with a =0 or =O. Minutes takes an integer value.

Keywords:  alerts=  collect=  detail=  instance=  history=  minutes=[5|15]  proxy=  request=  script=  status=  tips=  update=  webdav= 

As in the following example which enables history and status displays, and ensures alerts are disabled:

http://the.site.name/cgiplus-bin/alamode?history=1&status=1&alerts=0

Also refer logical name ALAMODE_QUERY in Configuration

deletes all current and stored data
invoke system print dialogue for this monitor
  (top left) The unlabeled checkbox located in the top-left of the monitor displays a section allowing the URLs for multiple à la mode sites (one per line) to be configured into a single display. Do not try to mix http:// and https:// specifications in any combination; browsers often block content with mixed security domains. Note that MonDeSi and à la mode URLs can be combined on the one display in either application, as well as DCLinabox terminal URLs.
activates à la mode in the same window
activates à la mode in a new, independent window. This window is sized precisely for the display and so resembles more a standalone application than a web page.
JavaScript link for a standalone à la mode suitable for embedding as an anchor or usefully, as a bookmarklet for addition to a browser's bookmarks/favorites
   the input elements of the configuration page
invoke system print dialogue for entire browser window

Comment

à la mode is understandably sensitive to the structure of the WASD global section. When this structure changes between versions à la mode at the very least will require rebuilding. The version string of à la mode tracks the version string of the corresponding WASD server. Where code or other major changes require changes in à la mode code the version will be bumped. Otherwise it is forward-compatible, with possible rebuild/link. The "tweak" of the version (third period-delimited character) is the "bugfix" and/or functionality update within the version of WASD it is released against.

à la mode does not lock the global section when reading values. This introduces the possibility of inconsistent resultant data. Atomic reads are OK (e.g. a longword or quadword (on non-VAX)). Data with relationships (e.g. peak processing and current processing count) with processing potentially occuring between the individual reads are an example. Another is the URI of the latest request data (read character by character and therefore subject to overwriting during the copy). Rather than introduce the expense of a lock to mitigate the risk (and potentially introducing unnecessary waits into server performance), for an observational application such as this it is considered an acceptable tradeoff.

à la mode accesses the WASD global lock environment used to coordinate and control WASD instances within a single system and across a cluster. As a consequence of participating in the control lock environment directives sent to the WASD envionment will report additional "instances" being notified. 

$ httpd/do=map
%HTTPD-I-DO, 2 instances notified; KLAATU::WASD:80-70, KLAATU::WASD:80

The "instances" relating to à la mode and those to servers should easily be differentiated by process name.

Installation

Is relatively straight-forward.

Update

An update follows the above installation steps, generally without the need to configure the application or modify the startup procedures (though check the release notes for any modification requirements). Instead ...

And remember that the more recent JavaScript will need to be (re)loaded into browsers (perhaps requiring browser cache clearing) and that a WASD CGIplus/WebSocket application will require any currently instantiated processes flushed with $ HTTPD/DO=DCL=DELETE (caution! - peremptorily removes all script processes).

Configuration

WebSocket access requires CGIplus. The script internally ensures this for the standard script activation path but this can also be implemented using a mapping rule. 

redirect /cgi-bin/alamode* ///cgiplus-bin/alamode*
...
exec+ /cgiplus-bin/* /cgi-bin/*

Other à la mode configuration items are set using logical names.

Display checkboxes can be configured by the request query string (see Usage) with default values configured using the logical name ALAMODE_QUERY as defined on the system executing à la mode. A request keyword overrides any equivalent found in the logical name value. For example the following definition ensures a history display is enabled unless overriden by a request ?history=0. This example also enables the status display. 

$ DEFINE /SYSTEM ALAMODE_QUERY "history=1&status=1"

Network Devices are automatically scanned for by à la mode, with any found used for NI statistics. If the system admin wishes to tailor the source of the statistics the multi-valued logical name ALAMODE_NI can be used to specify one or more network interfaces. Define this logical name system-wide (or in a script wrapper procedure) as required. 

$ DEFINE /SYSTEM ALAMODE_NI EWA0:,EWB0:

This logical name must exist as à la mode initialises. If undefined or the specified device(s) cannot be accessed the NI datum is greyed-out.

Excessive HTTP statuses may be alerted by defining one or more of the following logical names (these must exist as à la mode initialises).

The utility must be INSTALLed with required privileges. Concurrrent access to Network Interface (NI) data requires SHARE privilege, required if multiple utilities or instances of a utility are accessing the NI devices. SYSLCK is rquired for access to the server locks; SYSPRV for access to global sections data; and WORLD is required to access the instance (server process) data. 

$ INSTALL ADD CGI-BIN:[000000]ALAMODE.EXE /PRIV=(SHARE,SYSLCK,SYSPRV,WORLD)

à la mode may be proctored into existence. 

# WASD_CONFIG_GLOBAL
[DclScriptProctor]
1 /cgiplus-bin/alamode /cgiplus-bin/alamode

Geolocation

https://en.wikipedia.org/wiki/Geolocation

à la mode provides for a basic free geolocation service for the request host data. To enable use of geolocation define a logical name containing an asterisk for the default service, or the URL for an alternate service (see GEOLOCATE.C in the source directory). 

$ DEFINE /SYSTEM ALAMODE_GEOLOCATE "*"

The URI can be to the runtime directory (as above), an absolute URI elsewhere on the site, or a fully qualified URL for a completely independent server.

Access Control

As à la mode provides some insight into a server's processing and request detail the application insists on authorisation. It is suggested to place the script executable under the same access control as the server administration menu. For example: 

["VMS credentials"=WASD_VMS_RW=id]
/httpd/-/admin/* r+w,https:
/cgi*-bin/alamode* read,https:

At the very least, providing general access to a specified client address range: 

[WORLD]
/cgi*-bin/alamode* read,192.168.1.0/24,https:

If the username is WORLD then authenticated requests have the username and request URI display obfuscated (i.e. *********** out).

At the time of writing (mid 2017) not all (the major) browsers (Chrome, Edge, Firefox, Opera - not Safari) implement HTTP authorisation over WebSocket. WASD users employing WebSocket and authorisation are currently required to disable WebSocket for any other than these!

To disable WebSocket for all but selected user-agents define a multi-valued logical name with zero followed by values containing unique strings found in capable user-agent strings. 

$ DEFINE /SYSTEM ALAMODE_WEBSOCKET 0,"Chrome","Edge","Firefox","Opera"

Disabling WebSocket adds a little latency and server overhead to some actions, such as per-process display, but does not affect overall functionality.

Problems?

Releases

v12.0.b  22-APR-2022
•  geolocation now via GEOLOCATE.C (see Geolocation)
•  bugfix; physical memory size calculation
•  bugfix; various ..64 required ..64[HTTP12]
v12.0.a  24-OCT-2021
•  suitable for WASD v12.0.n
•  supports x86-64 VMS — if building Using IA64-hosted X86 Cross-Complier
•  VAX no longer implemented
•  move to native 64 bit data storage
•  proxy cache obsolete, proxy rework and SOCKS5 introduced
•  in line with WASD in general, moved to Apache 2.0 license
v11.3.d  07-MAR-2020
•  compatible with WASD v11.3 and v11.4
•  when a change in server PID is detected re-map the global section in case it was deleted in the interim
v11.3.c  20-JUL-2019
•  bugfix; WebSockAvailable()
v11.3.b  02-DEC-2018
•  bugfix; ALAMODE_GEOLOCATE and ALAMODE_QUERY; make SysTrnLnm2() static storage dynamic
v11.3.a  24-NOV-2018
•  compatible with WASD v11.3
•  allow configuration of checkboxes using request query string
•  logical name ALAMODE_QUERY provides default query string
•  geolocation has been completely refactored (with no default) to provide greater flexibility (if previously defined it will required reconfiguration)
v11.2.a  03-MAR-2018
•  compatible with WASD v11.2
•  add (instance) status report
v11.1.c  12-AUG-2017
•  request client geolocation
•  ALAMODE_GEOLOCATE logical name
v11.1.b  30-JUL-2017
•  ALAMODE_ALERT_NNN logical name and associated alerts
•  throttle data now wrap on overflow
v11.1.a  06-MAY-2017
•  compatible with WASD v11.1
v11.0.a  07-MAY-2016
•  compatible with WASD v11.0
•  could be used (with some limitations) against WASD v10.4
•  provide HTTP/2 and HTTP/1.n counts
v1.1.1  09-SEP-2015
•  allow for transient SS$_VALNOTVALID DLM status
•  bugfix; SS$_XVALNOTVALID 64/16 byte lock value block fallback
v1.1.0  15-AUG-2015
•  provide instance active/passive status
v1.0.2  21-APR-2015
•  bugfix; build.js fix [link] generation
•  bugfix; ensure JsonAlert()s do not occur prematurely
•  bugfix; ReportInstanceControl() 64 byte lock value
v1.0.1  11-APR-2015
•  workaround; establish server BYTLM from SYSUAF (per JPP)
•  bugfix; proxy graph data without Proxy[x]
•  bugfix; alamUsedBar() WSET calculation
•  bugfix; sys$gettim_prec defined beginning IA64 V8.4 breaking compile on earlier VMS (per JPP)
v1.0.0  05-APR-2015
•  initial

Acknowlegements