3.3.1

Amanda::Report modules list
Amanda modules list
List of All Modules
All Amanda Releases

Amanda::Report


NAME

Amanda::Report -- module for representing report data from logfiles


SYNOPSIS

    use Amanda::Report;
    my $report = Amanda::Report->new($logfile);
    my @hosts  = keys %{$report->{data}{disklist}};


INTERFACE

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}.

Creating a Report

  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.

Summary Information

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.

Report Data

  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.


DATA DESCRIPTION

Top Level

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.

Programs

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.

planner

The planner logs very little information other than determining what will be backed up. It has no special fields other than those given above.

driver

The driver has one field that the other program-specific entries do not:

start_time - the time it takes for the driver to start up.

amflush and amdump

No special fields.

dumper and chunker

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.

taper

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.

DLEs

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 ],
    };

Tries

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.

Parts

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.


ABOUT THIS PAGE

This page was automatically generated Tue Feb 21 19:14:01 2012 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.


3.3.1