Cfiltl, a filter for Mark Seger's "collectl"


DESCRIPTION

Cfiltl enables one to apply a grammar to the plot output of collectl. If you have ever used "cfilt" on Tru64, cfiltl will seem very familiar.

GRAMMAR

Components

The column-names ("tags") from collectl's output (with some minor adaptations) are used as placeholders for the values extracted from each record. One or more subsystem-expressions can be given to cfiltl. Multiple subsystem expressions can be provided for the same subsystem.

Subsystem-Expression

The format of a subsystem expression is (things between "[" and "]" are optional):

  <3-char-unique-subsystem-name>[s|+][=item1,item2,item3,...]:<tag-expr1>:<tag-expr2>:...:<tag-exprN>

Tag-Expression

A <tag-expr> is an arithmetic expression containing the grammatical components listed above. Tag-expressions are evaluated once for each collectl record.

Some examples:

user  simply extract the value in the user column for the subsystem
user+sysresult is sum of the values in the user and sys columns for the subsystem
int((user+sys)/8)add user and sys values, divide by 8, and truncate to integer value

Subsystem Selection

The first part of the subsystem-expression controls:

  1. what subsystem is chosen
  2. whether "summing" is enabled for the subsystem-expression
  3. whether summary or detail subsystem is desired
  4. for a detail subsystem, whether individual objects are selected

Some examples:
cpus    select CPU SUMMARY subsystem. Summing is not possible and will result in error. No selection-criteria can be specified for a summary subsystem.
cpu CPU detail subsystem. No selection-criteria, so summing is enabled by default.
cpu=0,1 CPU detail subsystem. Each tag-expression will be evaluated for CPUs 0 and 1, individually.
cpu+=0,1 CPU detail subsystem. Each tag-expression will be evaluated for the sum of the values for CPUs 0 and 1.

Normalization

Normalization means forcing data values into a particular range, by default between 0 and 100. This allows plotting of such data on the same graph with other data that either naturally falls into the same range, such as CPU load, which is always a percent, or data that has been similarly normalized.

There are two normalization notations:

  1. "old-style" -- A hash ("#") can be appended to a "tag" (column-name), with an optional number immediately following. This notation can only be used to normalize a single tag. It's available for convenience.
  2. "new-style" -- by using the pseudo-function "norm(<expression>[,<max>])". This allows normalization of an arbitrary expression, for example "norm(sqrt(rxkb+txkb))".
Normalization requires that causes cfiltl to read all records, store the relevant data in memory, and then calculate the "normalized" value for each record-value based on the highest overall value found in all collectl records.

Nested normalization ("norm(intrpt/norm(ctx))") is not allowed.

Some examples:
norm(rxkb+txkb)   normalize sum of received and transmitted KB (net) to the range 0-100
norm(rxkb+txkb,200)   normalize sum of received and transmitted KB (net) to the range 0-200
intrpt#   normalize cpu interrupt values to the range 0-100
intrpt#200 normalize to range 0-200

Summing

If a plus-sign is appended to a detail subsystem name, as in "cpu+", a tag in the tag-expression is replaced by the sum of all values in the corresponding column of collectl's output, or if a subset of objects in a subsystem has been selected, the sum for the selected objects. For example, to sum TxKB for "eth0" and "eth1":

  net+=eth0,eth1:TxKB

Specifying a detail subsystem without selecting any objects implies summing.

See the comments in the script for more detail.

TAG NAMING

Tag-names are taken from collectl's plot-format column-name headers with the following restrictions/exceptions:

Thus:

Wait%becomes "wait"
Intrpt/secbecomes "intrpt"
proc/secbecomes "proc"

Otherwise, tags must correspond 1-to-1 to column-names. Thus, proc and procque are two different tags.

EXAMPLES

RESTRICTIONS

The user is expected to apply a modicum of common sense when composing tag-expressions. For example, there are some collectl columns that contain string, and not numerical values, such as the User and Command columns in the PROCESS subsystem. If you use such tags in tag-expressions, cfiltl will happily perform the requested arithmetic -- the result will always be zero.

There are still some rough edges: I haven't figured out an easy way to check whether a subsystem in an expression exists, or whether data exists in the specified file for some subsystems, and a few other things, but it seems to work.

Also, I probably need to add some exceptions for naming some subsystems in subsystem-expressions.

Because of the way collectl formats data for plotting, cfiltl currently only understands plot output containing two kinds of data:

  1. one long line for most subsystems
  2. one process line per process
It will probably choke if it sees environmentals data, and possibly other data for which I have no test system or example output. Candidates are: Lustre, Interconnect.

If you would like me to add support for something that is currently missing, let me know.

DOWNLOAD

Current Version

cfiltl v1.4

Previous Versions

cfiltl v1.3

cfiltl v1.2


urban[at]tru64[dot]org