make printable

new: v1.0: - released

see also: trendPlotter, webNavbar databases none tqs tools webDocuSys; webNavbar output used by none upload/download upload/download scheme for config files; upload (scp) created web pages to standard QC web server

webKPI

Description

The tool webKPI helps to organize the KPI web pages. KPI stands for 'key performance indicator' and is meant to be a subsystem of the HC monitor, with a standardized content of KPI plots across all VLT instruments.

A KPI plot is a HC plot

• focussing on a key property of an instrument,
• displaying the FULL content of the instrument history,
• having a reference value to compare the actual data to (instead of acceptance thresholds).

An example for a KPI is resolution (resolving power) for a spectrograph, and gain for detectors. Click here for the GIRAFFE resolution plot.

Organizing all KPI plots per instrument is the core task of webKPI, together with creating a common page as entry point and a navigation bar as table of content.

Principles

The tool has a general configuration file and instrument-specific configuration files. The general configuration file is config.webKPI and contains

• the association of telescopes and instruments (relevant for the front page and the navigation bar),
• the supported KPI categories,
• the supported items.

In order to preserve the standardization, it is used as "master" for the normal user.

The instrument-specific configuration file is config.webKPI_<instrument>. It is filled and maintained by the normal user. It configures the names of KPI plots for the chosen KPI items and categories. The tool checks the choices against the general configuration file.

The normal user calls the tool only to set up or maintain the KPI page for the chosen instrument. The update of the KPI plots is not done by the tool, but by the usual HC monitor update mechanism.

Normal vs. general call

The normal call is

webKPI -i <myInstr>

or just

webKPI

As sketched below, the tool downloads the general configuration from qcweb (for consistency checks), and takes the local content config.webKPI_<myInstr> to create the result page for myInstr which is then uploaded to the HC monitor site. Also, the instrument configuration file is uploaded to the qcweb site and is the master for <myInstr> if needed.

The general call is

webKPI -A

(A stands for ALL). It can only be executed by the account hard-coded in the tool as $AUTHORIZED. In that mode, the tool takes the local config.webKPI as master, reading all instruments from it and creating the overview page Instrument_performance.html. In addition, it also loops across all configured instruments, downloads the corresponding config files from qcweb, executes the 'webKPI -i <instr>' calls, and uploads the InstrPerf_<instr>.html files. This loop is executed in order to always have the same design and concepts behind the individual pages. For this loop the tool makes use of all the config.webKPI_<instr> files maintained and uploaded by the individual accounts.

Finally, one can also call the tool as

webKPI -i <notMyInstr>

if e.g. a change is necessary and the corresponding QC scientist is not available. Then, after confirmation ("do you really want to"), one can call the tool for this specific instrument. The mechanism then is that both the config.webKPI and the config.webKPI_<notMyInstr> are downloaded from qcweb and used to create the specific output page for notMyInstr.

How to use

Type

webKPI -h for on-line help,

webKPI -v for the version number.

The standard mode is:

webKPI [-i <myInstr>]

Exceptionally, you can also call

webKPI -i <notMyInstr>

There is also the exploration mode,

webKPI -E

which gives an overview of the supported categories, the items per category, and who is $AUTHORIZED. This is useful when you need to start from scratch for a new instrument.

As $AUTHORIZED, you can also call

webKPI -A

which can be done as such interactively, or as

webKPI -A -n

without interactivity, designed for a cronjob. Type 'webKPI -E' to see who is $AUTHORIZED.

Output

The uploads of the config files go to http://qcweb.hq.eso.org/ALL/KPI/. You can directly connect to that link by clicking right of the text "back to overview". There you can see the pool of config files.

Configuration

All local tool configuration goes to $DFO_CONFIG_DIR/webKPI. There is config.webKPI and one config.webKPI_<myInstr>. For $AUTHORIZED, all other config.webKPI_<instr> are also in the local system.

The tool configuration config.webKPI has the following content:

Entries can be modified or added by the $AUTHORIZED account.

The instrument configuration config.webKPI_<instr> has the following content:

Find examples of webKPI config files here: http://qcweb.hq.eso.org/ALL/KPI/.

Navigation bar for KPI plots

For the KPI plot overview page to be linked properly to HC navigation bar, you include the following lines in the config.navbar_HC_<instr> file at the proper place (see the tool webNavbar for more):

as highlighted by the frame in the following screenshot of config.navbar_HC_GIRAFFE (at right the configuration, at left the result):

trendplotter configuration for KPI plots

The KPI plots are configured as part of the HC monitor, with the trendPlotter tool (see here).

• In the REPORT_NAME section of its config file, set RANGE=KPI and DESCR_FILE=<REPORT_NAME>.txt.
• The naming convention for KPI plots is to always have the report name starting with 'KPI_', like KPI_GAIN. The corresponding trendPlotter configuration file has the name config.tp_KPI_GAIN in this example.
• Make sure to always have REPORT_GROUP set to KPI.grp and VNAVBAR set to YES (to be consistent with the above navigation bar name vnavbar_HC_KPI.html).

The most important difference between a normal HC plot and a KPI plot is the reference value (to be entered in Sect 4.7 of the config file). While configuring a value is straightforward, finding it and distributing it to the upcoming QC documentation system webDocuSys is more involved. This is an IOT task and relies in particular on the close collaboration between QC scientist and instrument scientist.

Please also make sure to always have a file <REPORT_NAME>.txt filled with useful information about the reference value (which, why etc.). This displays in the report as "This plot" and is particularly useful for KPI plots.

Find an example of the config file for http://www.eso.org/observing/dfo/quality/GIRAFFE/reports/FULL/trend_report_KPI_SPECRES.html here:

config.tp_KPI_SPECRES