<html>
<head>
<link rel=stylesheet href="style.css" type="text/css">
<title>Read S-Expressions: readS</title>
</head>
<body>
<center><h1>Read S-Expressions: readS</h1></center>
<p>
<h3>Introduction</h3>
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 <i>collectl -scdN -c1 --sexpr rate -f /tmp</i>,
collectl will write one sample to /tmp/S which looks like the following:
<div class=terminal>
<pre>
(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))
</pre></div>
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 <i>readS</i> is supplied in
<i>/usr/share/collectl/util</i> but keep in mind since the utility is written
in perl, one needs to start the perl interpretter with each invocation and so
will generate addtional and perhaps unwanted overhead.
<p>
<h3>readS - the basics</h3>
When you type <i>readS</i> at the command line, you'll get the following usage
line displayed:
<pre>
usage: readS dir expr0 [oper1 expr1 [oper2 expr2...]
</pre>
The fields have the following meaning:
<p><table width=75%>
<tr valign=top><td width=10%><b>dir</b></td>
<td> </td>
<td colspan=2>directory containing s-exprission file S. If you appended <i>--sexpr</i>
to the <i>DaemonCommands</i> string in collectl.conf, this should be
specified as <i>/var/log/collectl</i>
</td></tr>
<tr valign=top><td><b>expr</b></td>
<td> </td>
<td colspan=2>This is an expression which typically references a data element in the
s-expr in the form <i>category.variable[.instance]</i>, where:
</td></tr>
<tr valign=top><td> </td><td> </td>
<td><b>category</b></td>
<td>names a major category in the s-expression such as <i>cputotals</i> or
<i>disktotals</i>
</td></tr>
<tr valign=top><td> </td><td> </td>
<td><b>variable</b></td>
<td>names a variable within a major category such as <i>sys</i> or
<i>reads</i>
</td></tr>
<tr valign=top><td> </td><td> </td>
<td><b>instance</b></td>
<td>names an instance of a variable such as <i>eth0</i>
</td></tr>
<tr valign=top><td> </td><td> </td>
<td colspan=2>alternatively you can specify a numeric constant
</td></tr>
<tr valign=top><td><b>oper</b></td><td> </td>
<td colspan=2>This is an arithmetic operator of either <i>+, - X or /</i>
noting that you cannot use * for multiplication but rather must use
an uppercase X.
</td></tr>
</table>
<p> when the expression(s) are evaluated, they are done so from left to right.
<h3>A couple of switches</h3>
There are several switches available, all optional, and if used they must immediately
follow the command itself and they are:
<p><table width=75%>
<tr valign=top><td width=10%><b>-d</b></td>
<td> </td>
<td>Enable debugging/tracing of the parsing process. Can be helpful
when there are errors reported and you're not sure why
</td>
</tr>
<tr valign=top><td><b>-h</b></td>
<td> </td>
<td>Prints <i>help</i> text with more detail than the <i>usage</i> line
</td>
</tr>
<tr valign=top><td><b>-p prec</b></td>
<td> </td>
<td>The precision of the output in decimal places. The default is 0
</td>
</tr>
<tr valign=top><td><b>-t</b></td>
<td> </td>
<td>Preface the output with the UTC timestamp
</td>
</tr>
<tr valign=top><td><b>-v</b></td>
<td> </td>
<td>Show version
</td>
</tr>
</table>
<h3>Examples</h3>
The following examples were run against the s-sexpression listed at the top of
this page, which was written to the /tmp directory.
<p><b>Report CPU system time</b>
<div class=terminal><pre>
readS /tmp cputotals.sys
20
</pre></div>
<p><b>Report Total user time along with debug trace</b>
<br>Notice that internally <i>readS</i> surrounds the user's request with plus signs
to make parsing easier.
<div class=terminal><pre>
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
</pre></div>
<p><b>Network Packets on eth1, including timestamp</b>
<div class=terminal><pre>
readS -t /tmp netinfo.netpktin.eth
1206045849.007 11
</pre></div>
<p><b>CPU idle as a fraction</b>
<div class=terminal><pre>
readS -p 2 /tmp cputotals.idle/100
0.55
</pre></div>
<p><b>dumb calculator</b>
<div class=terminal><pre>
readS -p 2 /tmp 10+20X30/2
450.00
</pre></div>
</body>
</html>
