Amanda::Report -- module for representing report data from logfiles
use Amanda::Report;
my $report = Amanda::Report->new($logfile); my @hosts = keys %{$report->{data}{disklist}};
This module reads the logfile passed to it and aggregates the data in
a format of nested hashes for convenient output. All data read in is
stored in $report->{data}
.
my $report = Amanda::Report->new($logfile, $historical);
The constructor reads the logfile and produces the report, which can then be
queried with the other methods. $logfile
should specify the path to the
logfile from which the report is prepared. If the logfile is not the "current"
logfile, then $historical
should be false. Non-historical reports may draw
information from the current Amanda environment, e.g., holding disks and info
files.
Note that most of the data provided by these methods is simply a reference to
data stored within the report, and should thus be considered read-only. For
example, do not use shift
or pop
to destructively consume lists.
my $datestamp = $report->get_timestamp();
This returns the run timestamp for this dump run. This is determined from one
of several START entries. This returns a full 14-digit timestamp regardless of
the setting of usetimestamps
now or during the dump run.
my @hosts = $report->get_hosts();
This method returns a list containing the hosts that have been seen in
a logfile. In a scalar context, get_hosts
returns the number of
hosts seen.
my @disks = $report->get_disks($hostname);
This method returns a list of disks that were archived under the given
$hostname
. In a scalar context, this method returns the number of
disks seen, belonging to the hostname.
my @dles = $report->get_dles();
This method returns a list of list references. Each referenced list contains a hostname & disk pair that has been reported by either the planner or amflush. The DLEs are stored in the order that they appear in the logfile.
@dles = ( [ 'example1', '/home' ], [ 'example1', '/var/log' ], [ 'example2', '/etc' ], [ 'example2', '/home' ], [ 'example3', '/var/www' ], );
if ( $report->get_flag($flag) ) { ... }
The get_flag
method accesses a number of flags that represent the state of
the dump. A true value is returned if the flag is set, and undef otherwise.
The available flags are:
got_finish
This flag is true when the driver finished correctly. It indicates that the dump run has finished and cleaned up.
degraded_mode
This flag is set if the taper encounters an error that forces it into degraded mode.
amflush_run
This flag is set if amflush is run instead of planner.
amvault_run
This flag is set if the run was by amvault.
normal_run
This flag is set when planner is run. Its value
should be opposite of amflush_run
.
dump_failed
If a dump failed.
dump_strange
If a dump end in strange result.
results_missing
If this was a normal run, but some DLEs named by the
planner do not have any results, then this flag is set. Users should look for
DLEs with an empty dump
key to enumerate the missing results.
historical
This flag is set if this is a "historical" report. It is based on the value passed to the constructor.
my $dle = $report->get_dle_info($hostname, $disk [,$field] );
This method returns the DLE information for the given $hostname
and disk
,
or if $field
is given, returns that field of the DLE information. See the
DATA DESCRIPTION section for the format of this information.
my $info = $report->get_program_info($program [,$field] );
This method returns the program information for the given $program
, or if
$field
is given, returns that field of the DLE information. See the DATA
DESCRIPTION section for the format of this information.
The data in the logfile is stored in the module at $report->{data}
.
Beneath that, there are a number of subdivisions that track both global and
per-host status of the given Amanda run that the logfile represents. Note that
these subdivisions are usually accessed via get_dle_info
and
get_program_info
, as described above.
$data->{programs}
the programs
key of the data points to a hash of global program
information, with one element per program. See the Programs section, below.
$data->{boguses}
The boguses
key refers to a list of arrayrefs of the form
[$prog, $type, $str]
as returned directly by Amanda::Logfile::get_logline
. These lines are not
in a recognized trace log format.
$data->{disklist}
The disklist
key points to a two-level hash of hostnames and
disknames as present in the logfile. It looks something like this:
$report->{data}{disklist} = { "server.example.org" => { "/home" => {...}, "/var" => {...}, }, "workstation.example.org" => { "/etc" => {...}, "/var/www" => {...}, }, };
Each {...}
in the above contains information about the corresponding DLE. See DLEs, below.
Each program involved in a dump has a hash giving information about its performance during the run. A number of fields are common across all of the different programs:
start
the numeric timestamp at which the process was started.
time
the length of time (in seconds) that the program ran.
notes
a list which stores all notes reported to the logfile by the corresponding program.
errors
a list which stores all errors reported to the logfile by the corresponding program.
Program-specific fields are described in the following sections.
The planner logs very little information other than determining what will be backed up. It has no special fields other than those given above.
The driver has one field that the other program-specific entries do not:
No special fields.
Most of the chunker's output and the dumper's output can be tied to a
particular DLE, so their programs
hashes are limited to notes
and
errors
.
The taper hash holds notes and errors for the per-instance runs of the taper program, but also tracks the tapes seen in the logfile:
tapes
This field is a hash reference keyed by the label of the tape. each value of the key is another hash which stores date, size, and the number of files seen by this backup on the tape. For example:
$report->{data}{programs}{taper}{tapes} = { FakeTape01 => { label => "FakeTape01", date => "20100318141930", kb => 7894769, # data written to tape this session files => 14, # parts written to tape this session dle => 13, # number of dumps that begin on this tape time => 2.857, # time spent writing to this tape }, };
tape_labels
The tape_labels
field is a reference to a list which records the
order that the tapes have been seen. This list should be used as an
ordered index for tapes
.
In the below, $dle
is the hash representing one disklist entry.
The estimate
key describes the estimate given by the planner. For
example:
$dle->{estimate} = { level => 0, # the level of the backup sec => 20, # estimated time to back up (seconds) nkb => 2048, # expected uncompressed size (kb) ckb => 1293, # expected compressed size (kb) kps => 934.1, # speed of the backup (kb/sec) };
Each dump of the DLE is represented in $dle->{dumps}
. This is a hash,
keyed by dump timestamp with a list of tries as the value for each dump. Each
try represents a specific attempt to finish writing this dump to a volume. If
an error occurs during the backup of a DLE and is retried, a second try is
pushed to the tries list. For example:
$dle->{dumps} = { '20100317142122' => [ $try1 ], '20100318141930' => [ $try1, $try2 ], };
A try is a hash with at least one dumper, taper, and/or chunker DLE program as a key. These entries contain the results from the associated program during try.
There are a number of common fields between all three elements:
date
a timestamp of when the program finished (if the program exited)
status
the status of the dump at this program on this try ("success", "partial",
"done", or "failed"). The planner adds an extra "skipped" status which is
added when the planner decides to skip a DLE due to user configuration (e.g.,
skipincr
).
level
the incremental level of the backup.
sec
the time in seconds for the program to finish.
kb
the size of the data dumped in kb.
kps
the rate at which the program was able to process data, in kb/sec.
error
if the program fails, this field contains the error message
The dumper
hash has an orig_kb
field, giving the size of the data dumped
from the source, before any compression. If encountered, the dumper
hash may
also contain a stranges
field, which is a list of all the messages of type
L_STRANGE
encountered during the process.
The taper
hash contains all the exit status data given by the taper.
Because the same taper process handles multiple dumps, it does not have a
date
field. However, the taper does have an additional field, parts
,
containing a list of parts written for this dump.
Each item in the list of taper parts is a hash with the following fields:
label
the name of the tape that the part was written to.
date
the datestamp at which this part was written.
file
the filename of the part.
part
the sequence number of the part for the DLE that the part is archiving.
sec
the length of time, in seconds, that the part took to be written.
kb
the total size of the part.
kps
the speed at which the part was written.
This page was automatically generated Tue Oct 4 19:45:37 2016 from the Amanda source tree, and documents the most recent development version of Amanda. For documentation specific to the version of Amanda on your system, use the 'perldoc' command.