/ 
PBS-Logs-0.05
River stage zero No dependents
/ PBS::Logs::Acct

NAME

PBS::Logs::Acct - parses the PBS accounting log files and inherits from PBS::Logs.

SYNOPSIS

See the sections below:

use PBS::Logs::Acct;

The only non-inheritable function is the class level debug()

PBS::Logs::Acct::debug()

You must use

PBS::Logs::debug()

to read or set global debugging. However, the instance version works just fine:

$pl->debug()

Other than that PBS::Logs::Acct inherits all the methods that are available from PBS::Logs, plus adds the methods listed below.

DESCRIPTION

EXPORT

Can export message_hash() and message_hash_dump()

SEE ALSO

PBS::Logs
PBS::Logs::Event
The PBS Pro 5.4 Administrator Guide

AUTHOR

Dr R K Owen, <rkowen@nersc.gov>

COPYRIGHT AND LICENSE

Copyright (C) 2005 The Regents of the University of California

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details, which can be found at:

http://www.gnu.org/copyleft/lesser.html
or	http://www.opensource.org/licenses/lgpl-license.php

new

Create a PBS::Logs::Acct object. It takes only one argument which is either a filename, array reference, or a FILE glob reference.

See PBS::Logs::new for examples and specifics.

get()

Get the next accounting log entry. Extends PBS::Logs::get() by filtering based on record_types. See PBS::Logs::Acct::filter_records() below for more info on this filtering, and PBS::Logs::get() for info on return values.

Special Arrays

The following special associative arrays (hashes) are provided by this package, which may be useful for translating between arrays returned by the get() method to/from hashes returned by the get_hash() method, or for selecting a subset of the log entry.

%PBS::Logs::Acct::num2keys

Relates array position (number) to the keys (or field descriptions) of a get_hash() generated hash.

%num2keys = (
      0       => 'datetime',
      1       => 'record_type',
      2       => 'id',
      3       => 'message'
);

%PBS::Logs::Acct::keys

Relates keys (field descriptions) as used by the get_hash() method to array positions (number) as returned from the get() method. Essentially, just the inverse of %PBS::Logs::Acct::num2keys above.

%PBS::Logs::Acct::record_type

Describes the record types, which are keys to this hash array.

%record_type = (
      'A'     => 'job aborted by server',
      'B'     => 'resource reservation period begin',
      'C'     => 'job checkpointed and held',
      'D'     => 'job deleted by request',
      'E'     => 'job ended',
      'F'     => 'resource reservation period finish',
      'K'     => 'removal of resource reservation by sheduler or server',
      'k'     => 'removal of resource reservation by client',
      'Q'     => 'job queued',
      'R'     => 'job rerun',
      'S'     => 'job execution started',
      'T'     => 'job restarted from checkpoint',
      'U'     => 'unconfirmed resource reservation created by server',
      'Y'     => 'confirmed resource reservation created by scheduler',
);

get_hash()

Like the PBS::Logs::Acct::get() method; however, instead of returning an array reference, it (obviously) returns a hash where the keys are the same keys as given by %PBS::Logs::Acct::keys .

The accounting log entry looks like this with respect to the keys:

datetime;record_type;id;message

where the message field can have several key=value pairs depending on the record_type and all the new-lines have been replaced with spaces.

If in a scalar mode it will return a hash reference else it returns a hash.

filter_records(\@array_reference_list_of_record_types)

filter_records(@array_list_of_record_types)

Sets or reads the record_type filter for the get() method.

get() or get_hash() will only retrieve lines that have a record_type in the list given.

Sending an empty array reference will clear the record_type filtering.

It will return '1' if successful, else undef if some warning occurs.

If no arguments are given then the method will return an array of record_types filtered.

message_hash($message_text)

Parses an accounting log message and returns an associative array (hash) containing the key/value pairs. And for certain fields, such as: Resource_List and resources_used, the value is another hash array containing the resource key and value. Can be called either as a method of an instantiated object, or as a class function.

An example of the message text with resources_used dotted field:

...
resources_used.cpupercent=0 resources_used.cput=00:00:00
resources_used.mem=2880kb resources_used.ncpus=4
resources_used.vmem=6848kb resources_used.walltime=00:00:00
...

Results in a hash array of:

...
resources_used => {
   cpupercent => 0,
   cput => 00:00:00,
   mem => 2880kb,
   ncpus => 4,
   vmem => 6848kb,
   walltime => 00:00:00
}, ...

message_hash_dump($message_hash)

Takes the hash returned by message_hash() and recursively dumps the keys and values into a string suitable for viewing or evaluation. Can be called either as a method of an instantiated object, or as a class function.

Example of evaluating the output:

my $m = PBS::Logs::Acct::message_hash($some_message);
my $t = PBS::Logs::Acct::message_hash_dump($m);
my $x;
eval "\$x = $t";	# $x is now a HASH reference, equivalent to $m