Exporting Custom Output

Introduction

These modules all end in the extension .ph and are searched for first in the directory collectl is being executed from and then /usr/share/collectl. If the module name is prepended with a directory name, collectl will search only there.

The reason you might care about this is that now if you want to produce your own exportable form of output and be able to print it locally, make it available to another program over a socket or even write to a local file while still being able to log to raw and/or plot formats, you get that all that functionality for free.

How It Works

• name both names a file to be required by collectl as well as the name of the entry points to both an initialization routine as well as one that produces the output
• options specifies an optional list of arguments that are passed to both routines to do with whatever they wish

• gexpr allows one to send collectl data to ganglia
• graphite allows one to send collectl data to graphite
• lexpr generates output in an easy to parse format
• proctree provides another way to look at process data
• vmstat is the standard unix vmstat command most people know and love, so why reinvent it? It's both a useful example of how to write an export as well as provides the benefit of allowing one to play back collectl data in vmstat format!

Logging
Collectl can actually create up to 3 different type of log files and it's worth spending a little more time enumerating how collectl decides where and when to create them.

• In its simplest form, when one runs collectl with --export and no options, all output is sent to the terminal, noting gexpr and graphite always require an address.
• If collectl is run with -f, and one is exporting with lexpr a snapshot file is created in the directory associated with -f.
• If a socket is to be used by specifying collectl -A and the export supports socket I/O:
• all output goes out over the socket and no snapshot file is involved
• if one specifies -f, a raw file is created in the directory specified by -f. If -P is also used, a plot file is created instead and if -P and --rawtoo are used, both types of files are created. caution: this is different behavior than one sees when running without sockets in which case a snapshot file is written to the directory named by -f
• Since gexpr and graphite do not use -A for specifying socket I/O and do their own communications, collectl's rules for non-socket logging apply, in which case -f by itself implies a snapshot file is involved and so requires -P or --rawtoo or both to do any logging.
• To create the snapshot file in a directory other then the one specified with -f, use the f= option with --export
• If one tries an invalid combination of switches or something not supported, it is up to the export itself to determine that since by design collectl has no knowledge of those module's inner workings.

Example

This first section gets called almost immediately by collectl after reading in the various user switches. This is the place to catch switch errors and since this routine always requires -scm we'll just hardcode it to that and reject any user entered ones. This initialization subroutine must be named for our module followed by Init.

sub vmstatInit
{
  error("-s not allowed with 'vmstat'")          if $userSubsys ne '';
  error("-f requires either --rawtoo or -P")     if $filename ne '' && !$rawtooFlag && !$plotFlag;
  error("-P or --rawtoo require -f")             if $filename eq '' && ($rawtooFlag || $plotFlag);
  $subsys=$userSubsys='cm';
}

The if statement uses collectl's standard idiom for printing headers based on the number of lines printed and whether or not the user wants only a single header, no header or even to clear the screen between headers.

sub vmstat
{
  my $line;
  if (printHeader())
  {
    $line= "${cls}#${miniBlanks}procs ---------------memory (KB)--------------- --swaps-- -----io---- --system-- ----cpu-----\n";
    $line.="#$miniDateTime r  b   swpd   free   buff  cache  inact active   si   so    bi    bo   in    cs us sy  id wa\n";
  }

  my $datetime='';
  if ($options=~/[dDTm]/)
  {
    ($ss, $mm, $hh, $mday, $mon, $year)=localtime($lastSecs);
    $datetime=sprintf("%02d:%02d:%02d", $hh, $mm, $ss);
    $datetime=sprintf("%02d/%02d %s", $mon+1, $mday, $datetime)                  if $options=~/d/;
    $datetime=sprintf("%04d%02d%02d %s", $year+1900, $mon+1, $mday, $datetime)   if $options=~/D/;
    $datetime.=".$usecs"                                                         if ($options=~/m/);
    $datetime.=" ";
  }

  my $i=$NumCpus;
  my $usr=$userP[$i]+$niceP[$i];
  my $sys=$sysP[$i]+$irqP[$i]+$softP[$i]+$stealP[$i];
  $line.=sprintf("%s %2d %2d %6s %6s %6s %6s %6s %6s %4d %4d %5d %5d %4d %5d %2d %2d %3d %2d\n",
                $datetime, $procsRun, $procsBlock,
                cvt($swapUsed,6,1,1),  cvt($memFree,6,1,1),  cvt($memBuf,6,1,1),
                cvt($memCached,6,1,1), cvt($inactive,6,1,1), cvt($active,6,1,1),
                $swapin/$intSecs, $swapout/$intSecs, $pagein/$intSecs, $pageout/$intSecs,
                $intrpt/$intSecs, $ctxt/$intSecs,
                $usr, $sys, $idleP[$i], $waitP[$i]);

  printText($line);
}
1;