Read S-Expressions: readS

Introduction

As you know (or should know), you can request collectl to write data in the format of an s-expression and if you run the command collectl -scdN -c1 --sexpr rate -f /tmp, collectl will write one sample to /tmp/S which looks like the following:
(sample (time 1206019962.007))
(cputotals (user 10) (nice 5) (sys 20) (wait 10) (irq 0) (soft 0) (steal 0) (idle 55))
(ctxint (ctx 20) (int 99) (proc 0) (runq 133))
(disktotals (reads 10)) (readkbs 200) (writes 0) (writekbs 0))
(netinfo
  (name eth0 eth1 ib0 ib1)
  (netkbin 0 1 0 0)
  (netpktin 0 11 0 0)
  (netkbout 0 1 0 0)
  (netpktout 0 8 0 0))
This file will be continously overwritten with each sample collectl takes. In other words, any external appliction can at any time it wishes read this file and see all the date in one, easy to read, compact form. To facilitate the reading of this file the tool readS is supplied in /opt/hp/collectl/sbin as well as a soft link to it in /usr/sbin.

readS - the basics

When you type readS at the command line, you'll get the following usage line displayed:
usage: readS dir expr0 [oper1 expr1 [oper2 expr2...]
The fields have the following meaning:

dir   directory containing s-exprission file S. If you appended --sexpr to the DaemonCommands string in collectl.conf, this should be specified as /var/log/collectl
expr   This is an expression which typically references a data element in the s-expr in the form category.variable[.instance], where:
   category names a major category in the s-expression such as cputotals or disktotals
   variable names a variable within a major category such as sys or reads
   instance names an instance of a variable such as eth0
   alternatively you can specify a numeric constant
oper  This is an arithmetic operator of either +, - X or / noting that you cannot use * for multiplication but rather must use an uppercase X.

when the expression(s) are evaluated, they are done so from left to right.

A couple of switches

There are several switches available, all optional, and if used they must immediately follow the command itself and they are:

-d   Enable debugging/tracing of the parsing process. Can be helpful when there are errors reported and you're not sure why
-h   Prints help text with more detail than the usage line
-p prec   The precision of the output in decimal places. The default is 0
-t   Preface the output with the UTC timestamp
-v   Show version

Examples

The following examples were run against the s-sexpression listed at the top of this page, which was written to the /tmp directory.

Report CPU system time

readS /tmp cputotals.sys
20

Report Total user time along with debug trace
Notice that internally readS surrounds the user's request with plus signs to make parsing easier.

readS -d cputotals.user + cputotals.nice
Processing: +cputotals.user + cputotals.nice+
  Oper: +  Expr: cputotals.user  Leftover: + cputotals.nice+
  Value: 10  Subtotal: 10
Processing: + cputotals.nice+
  Oper: +  Expr: cputotals.nice  Leftover: +
  Value: 5  Subtotal: 15
15

Network Packets on eth1, including timestamp

readS -t /tmp netinfo.netpktin.eth
1206045849.007 11

CPU idle as a fraction

readS -p 2 /tmp cputotals.idle/100
0.55

dumb calculator

readS -p 2 /tmp 10+20X30/2
450.00