Query the vovserver

The vovselect command provides a way to retrieve specific data from the vovserver, with filtering done on the server side. This method is differs from some of the VTK calls, which get all data and require processing on the client side to get the data of interest.

Attention: In an upcoming major release of Accelerator Products, the vovselect * wildcard select feature will be dropped. To prepare for this change, users should update scripts and REST requests to issue vovselect requests using a specified list of field names. For example:

nc cmd vovselect statusnc,id,command from jobs

An easy way to find out what fields are in an object type is by using vovselect fieldname. For example:

nc cmd vovselect fieldname from jobs

Many types of objects in the vovserver may be queried. See the help information below for the supported objects.
Note: vovselect supports the "*" wildcard to signify all fields of a particular object. Be sure to quote the * character as required by your shell, e.g.: vovselect '*' from jobs where idint==12345
Run vovselect fieldname,fieldtype from <object> to see the list of fields for that object. Multiple fields may be requested by separating them with a comma. Some fields represent a data collection that can be broken down using a format of FIELD.X, such as: 
KEY.<KEYNAME>       (metric objects)
PARAM.<PARAMNAME>   (server object)
PROP.<PROPNAME>     (all objects)
RESOURCES.<RESNAME> (tasker objects)

GRABBEDRESOURCES.<name> only returns a value for the corresponding central resource when the job is currently running.

SOLUTION.<name> returns a value for the corresponding hardware resource after the job has started running. The value persists after the job has terminated.

RESOURCES.<name> attempts to determine a value for the corresponding requested resource. If the job is running, then the actual value of the allocated resource is returned. If the job is not running, the query will estimate a value by looking for the first matching value in the requested resource string. This may result in an underestimate, or an incorrect value.

For example, with the request: -r "RAM/20 RAM/30", RESOURCES.RAM may return "20" or "50" depending on the scheduling phase of the job. A contrived example which illustrates the difficulty of computing a value would be -r "( RAM/100 CLOCK/10 ) OR ( RAM/50 CLOCK/20)". RESOURCES.RAM returns exactly the same value as REQRAM, and similarly for CORES, PERCENT, SLOTS & SWAP.

Examples

Queries you can run include the following:
  • RESOURCES.<RESNAME> estimates the requested resource value of RESNAME. It attempts to determine a value for the corresponding requested resource. If the job is running, then the actual value of the allocated resource is returned. If the job is not running, the query will estimate a value by looking for the first matching value in the requested resource string. This may result in an underestimate, or an incorrect value.

    For example, with the request -r "RAM/20 RAM/30", RESOURCES.RAM may return "20" or "50" depending on the scheduling phase of the job. A contrived example which illustrates the difficulty of computing a value would be -r "( RAM/100 CLOCK/10) OR ( RAM/50 CLOCK/20 )". RESOURCES.RAM returns exactly the same value as REQRAM, and similarly for CORES, PERCENT, SLOTS & SWAP.

  • GRABBEDRESOURCES.<RESNAME> returns the current value of RESNAME in a job's grabbed resources. It only returns a value for the corresponding central resource when the job is currently running.
  • SOLUTION.<RESNAME> returns the value of RESNAME in a job's solution. It returns a value for the corresponding hardware resource after the job has started running. The value persists after the job has terminated.
For example, the following job submission 
$ nc run -r "RAM/30 License:MATLAB/2" – sleep 1000
vovselect produces the following output:
$ nc cmd vovselect -header id,RESOURCES.RAM,RESOURCES.License:MATLAB from jobs 
id RESOURCES.RAM RESOURCES.License:MATLAB 
000001366 30 2

If the query is unable to determine a value, it will return an empty string.

If the query is used inside a 'where' clause, it may need to be quoted, such as, -where '"grabbedresources.License:MATLAB">1'.

For example, if the following job executes: 
$ nc run -r License:MATLAB/2 – sleep 1000
vovselect produces the following output: 
$ nc cmd vovselect -header id,statusnc,GRABBEDRESOURCES.License:MATLAB,SOLUTION.RAM from jobs -where 
'"GRABBEDRESOURCES.License:MATLAB">1' 
id statusnc GRABBEDRESOURCES.License:MATLAB SOLUTION.RAM 
000001202 Running 2 20

vovselect

vovselect: Usage Message

    Utility to query vovserver data.

    USAGE:

      vovselect <FIELDSPEC> from <OBJECT> [OPTIONS]

    OPTIONS:

      -h               -- Show usage syntax.
      -v               -- Increase verbosity.
      -where <FILTER>  -- Filter the results.
      -order <COLUMN> [ORDER]  -- Sort the output by the specified column
                                    and ordering. Ordering is either "asc"
                                    (ascending)  or "desc" (descending).
                                    Default ordering is ascending.  When
                                    specifying an ordering, place the column
                                    and ordering in quotes, e.g.
                                    -order 'name desc'.
      -limit <N>       -- Limit the output to N rows.
      -distinct        -- Return distinct rows.

      -header          -- Displays column headers in the output.
      -cache 0/1       -- Control cacheing of query (default is 1).
                          Tech Note: use cache 0 for small results
                          (less than a few thousand rows)

      If option values contain shell-sensitive characters, such as ">",
      enclose them with single quotes (Linux) or double quotes (Windows).

      The from parameter will accept queryable object names (as listed by
      "vovselect objectname from objects"), individual object identifiers
      (as listed by "vovselect idint from <object>"), or set names
      (as listed by "vovselect name from sets").  This parameter can also
      accept the following:
         SUBSETS.<SETID>
         MATCHES.<RESMAPID>
         MATCHES.<RESMAPNAME>

    SUPPORTED OBJECTS:
      Run "vovselect objectname from objects" to see
      the list of queryable objects.

    SUPPORTED FIELDS:

      Run "vovselect fieldname,fieldtype from <object>" to see the list of
      fields for that object. To see a list of fields with descriptions run,
      "vovselect fieldname,fielddesc from <object>". Multiple fields may be
      requested by separating them with a comma. Some fields represent a data
      collection that can be broken down using a format of FIELD.X, such as:
         GRABBEDRESOURCES.<RESNAME>     (job objects)
         KEY.<KEYNAME>                  (metric objects)
         PARAM.<PARAMNAME>              (server object)
         PROP.<PROPNAME>                (all objects)
         RESOURCES.<RESNAME>            (tasker & job objects)
         SOLUTION.<RESNAME>             (job objects)

    SUPPORTED FILTERS:

      Use selection rule operators in conjunction with field names to filter
      queries. See operator list at URL/doc/html/vov/topics/vov/operators.htm
      via web browser. To get the current the URL for current instance,
      execute the vovbrowser command.

    EXAMPLES:

      % vovselect -h
      % vovselect objectname from objects
      % vovselect fieldname from server
      % vovselect id,name from users -order name -limit 10 -header
      % vovselect id,name from users -where 'name==joe'
      % vovselect id,name from 12345
      % vovselect id,name from subsets.23456
      % vovselect matchtype,host from matches.License:spice
      % vovselect idint,name from users -where 'idint>3600'
                  -order 'idint desc'
      % vovselect id,age from System:running
      % vovselect id,age -from System:running -cache 0

Use vovselect for Querying

The nc hosts command can be used for querying, but it can sometimes take several minutes to return results, which causes some nodes to show up as "N/A". nc hosts will query the server and return significant amounts of data, but the server loading will directly affect the response time of the command.

In order to avoid such delay, you can use vovselect to run the query, as it prefilters the output server-side before returning it to the client.

Use the table below to understand the mapping of fields between the nc hosts and vovselect commands.

nc hosts vovselect from TASKERS vovselect from HOSTS
ARCH ARCH ARCH
CAPABILITIES CAPABILITIES NA
CAPACITY CAPACITY CPUS
CLASSRESOURCES CLASSRESOURCES NA
CLOCK CLOCK CPUCLOCK
COEFF COEFF NA
CONSUMABLES CONSUMABLES NA
CORES CORESAVAIL NA
CORESAVAIL CORESAVAIL NA
CORESTOTAL CORESTOTAL CPUS
CORESUSED CORESUSED NA
CPUS CPUS CPUS
CURLOAD CURLOAD NA
DOEXEC DOEXEC NA
DONETINFO DONETINFO NA
DOPROCINFO DOPROCINFO NA
DORTTRACING DORTTRACING NA
EFFLOAD NA NA
EXTRAS EXTRAS NA
FULLINFO FULLINFO NA
GROUP GROUP NA
HB NA NA
HBPP NA NA
HEARTBEAT HEARTBEAT NA
HOST HOST NAME
ID ID NA
IDINT IDINT NA
LASTJOBID NA NA
LASTUPDATE LASTUPDATE NA
LIFETIMEJOBS LIFETIMEJOBS NA
LOAD1 NA NA
LOAD15 NA NA
LOAD5 NA NA
LOADEFF NA NA
MACHINE MACHINE MACHINE
MANUALPOWER NA NA
MAXLOAD MAXLOAD NA
MESSAGE MESSAGE NA
MESSAGESYS MESSAGESYS NA
MESSAGEUSER MESSAGEUSER NA
MODEL MODEL NA
NAME NAME NAME
NUMJOBS NA NA
OSCLASS OSCLASS NA
PERCENT PERCENT NA
PERSISTENT PERSISTENT NA
PID PID NA
POWER POWER NA
RAM RAM NA
RAMFREE RAMFREE NA
RAMTOTAL RAMTOTAL RAMTOTAL
RAWPOWER NA NA
RELEASE RELEASE NA
RESERVEDBY RESERVEDBY NA
RESERVEEND RESERVEEND NA
RESERVEFORBUCKETID RESERVEFORBUCKETID NA
RESERVEFORID RESERVEFORID NA
RESERVEGROUP RESERVEGROUP NA
RESERVEJOBCLASS RESERVEJOBCLASS NA
RESERVEJOBPROJ RESERVEJOBPROJ NA
RESERVEOSGROUP RESERVEOSGROUP NA
RESERVESTART RESERVESTART NA
RESERVEUSER RESERVEUSER NA
RESOURCECMD RESOURCECMD NA
RESOURCES NA NA
RESOURCESEXTRA NA NA
RESOURCESPEC RESOURCESPEC NA
RUNNINGJOBS RUNNINGJOBS NA
SLOTS NA NA
SLOTSTOTAL SLOTSTOTAL NA
STATSREJECTCORES STATSREJECTCORES NA
STATSREJECTOTHER STATSREJECTOTHER NA
STATSREJECTRAM STATSREJECTRAM NA
STATSREJECTRESERVED STATSREJECTRESERVED NA
STATSREJECTSLOTS STATSREJECTSLOTS NA
STATSVISITS NA NA
STATUS NA NA
SWAP SWAP NA
SWAPFREE SWAPFREE NA
SWAPTOTAL SWAPTOTAL NA
TASKERGROUP TASKER NA
TASKERNAME TASKERNAME NAME
TASKERSLOTSSUSPENDABLE TASKERSLOTSSUSPENDABLE NA
TASKERSLOTSSUSPENDED TASKERSLOTSSUSPENDED NA
TASKERSLOTSUSED TASKERSLOTSUSED NA
TASKERTYPE TASKERTYPE NA
TIMELEFT TIMELEFT NA
TMP TMP NA
TYPE TYPE NA
UPTIME NA NA
UPTIMEPP UPTIMEPP NA
USER USER NA
VERSION VERSION NA
VOVVERSION VOVVERSION NA