NAME

Linux::Taskstats::Read - Read Linux taskstats structures

SYNOPSIS

  use Linux::Taskstats::Read;

  my $ts = new Linux::Taskstats::Read( -file => '/some/taskstats.log' -ver => 3 );
  while( my $rec = $ts->read ) {
    printf("Comm: %s (uid: %d)\n", $rec->{ac_comm}, $rec->{ac_uid});
  }
  $ts->close;

DESCRIPTION

The Linux 2.6.19 kernel introduced real-time task and process statistical accounting routines. These stats are requested and gathered via a netlink interface. This module does not interface with netlink, but it can read a raw binary dump of a taskstats struct (either from memory or from disk).

new()

Creates a new taskstats record reader object. Parameters:

-file

Specifies a file to open. This file should be a binary dump of taskstats objects (e.g. such as produced by getdelays).

-ver

Specifies the taskstats struct version. This is a required parameter. Try '3' if you don't know what version to use. Otherwise, look near the top of linux/taskstats.h to see your kernel's current version.

read()

Reads a taskstats record from the file specified in either the constructor (new()) or open().

  my $rec = $ts->read;

read_raw()

Returns a raw (packed) taststats structure.

close()

When you're done reading what you need from the taststats dump, kindly close the file.

Example:

  $ts->close();

open()

If you don't know the filename at the time of object construction, or you've closed the object's filehandle (via close()), you can (re-)open a new file with this method.

Example:

  $ts->open('/path/to/some/file.log');

fields()

Returns a list containing all of the fields of the taskstats structure in the order they appear in taskstats.h.

Example:

  my @fields = $ts->fields;

size()

Returns the record size in bytes for the current taskstats version.

Example:

  my $size = $ts->size;

template()

Returns the template for unpack() for this taskstats version.

Example:

  my $rec = $ts->read_raw;
  @data = unpack($ts->template, $rec);

version()

Returns the taskstats version this object is currently set to parse.

Example:

  print $ts->version . "\n";

TASKSTATS STRUCT

A taskstats struct, as returned by read() has the following fields you can examine (this is the version 3 format):

  version
  ac_exitcode
  ac_flag
  ac_nice
  cpu_count
  cpu_delay_total
  blkio_count
  blkio_delay_total
  swapin_count
  swapin_delay_total
  cpu_run_real_total
  cpu_run_virtual_total
  ac_comm
  ac_sched
  ac_pad
  ac_uid
  ac_gid
  ac_pid
  ac_ppid
  ac_btime
  ac_etime
  ac_utime
  ac_stime
  ac_minflt
  ac_majflt
  coremem
  virtmem
  hiwater_rss
  hiwater_vm
  read_char
  write_char
  read_syscalls
  write_syscalls
  read_bytes
  write_bytes
  cancelled_write_bytes

More information on what is stored in these fields may be found in the documentation supplied by your kernel. These fields are subject to change depending on the taskstats version used. They are supplied here only as a courtesy and reference. Future versions may or may not be included in subsequent releases of this module.

TROUBLESHOOTING

Q. I have no idea what this modules is for! What is it for?

A. Linux::Taskstats::Read can read taskstats dumps. If you don't know what taskstats is, you probably don't need this module (but you can find out more by reading the 'SEE ALSO' references below).

Q. I get "Invalid type 'Q' in unpack at .../Linnux/Taskstats/Read.pm" errors.

A. You're not on a 64-bit box (or your kernel has not been built with 64-bit support). This module has to be used on a box that can build and run taskstats (but may not necessarily be running it at the moment).

Q. How can I make taskstats dumps that this module can read?

A. See the getdelays program in the 'SEE ALSO' section below for an example program.

Q. I can't get getdelays to run on my system.

A. Try a 2.6.2x kernel or higher (apparently there were some problems in the 19 kernel). Beyond that, check with your kernel vendor for additional support.

NOTES

The major version of this module will match the latest version of the taskstats struct it supports natively (e.g., 3.xx for taskstats version 3, etc.).

SEE ALSO

The following documents in the 2.6.19 or higher Linux kernel sources (under the Documentation/accounting directory):

taskstats.txt
delay-accounting.txt
taskstats-struct.txt
taskstats.h
getdelays.c

AUTHOR

Scott Wiersdorf, <scott@perlcode.org>

COPYRIGHT AND LICENSE

Copyright (C) 2007 by Bluehost, Inc.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.