X-Git-Url: https://git.gag.com/?p=debian%2Famanda;a=blobdiff_plain;f=perl%2FAmanda%2FReport.pm;h=48bd05a72eb6470ec90b4f032f9b2105dea53b51;hp=a94912aaa9a2cd925892a546834196585e205516;hb=b116e9366c7b2ea2c2eb53b0a13df4090e176235;hpb=fd48f3e498442f0cbff5f3606c7c403d0566150e diff --git a/perl/Amanda/Report.pm b/perl/Amanda/Report.pm index a94912a..48bd05a 100644 --- a/perl/Amanda/Report.pm +++ b/perl/Amanda/Report.pm @@ -43,7 +43,9 @@ 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 C<< $report->{data} >>. -=head2 my $report = Amanda::Report->new($logfile, $historical); +=head2 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. C<$logfile> should specify the path to the @@ -52,25 +54,31 @@ logfile, then C<$historical> should be false. Non-historical reports may draw information from the current Amanda environment, e.g., holding disks and info files. -=head2 my $datestamp = $report->get_timestamp(); +=head2 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 C or C 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 C now or during the dump run. -=head2 my @hosts = $report->get_hosts(); + my @hosts = $report->get_hosts(); This method returns a list containing the hosts that have been seen in a logfile. In a scalar context, C returns the number of hosts seen. -=head2 my @disks = $report->get_disks($hostname); + my @disks = $report->get_disks($hostname); This method returns a list of disks that were archived under the given C<$hostname>. In a scalar context, this method returns the number of disks seen, belonging to the hostname. -=head2 my @dles = $report->get_dles(); + 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 @@ -85,70 +93,153 @@ in the logfile. [ 'example3', '/var/www' ], ); -=head2 my $dle = $report->get_dle_info($hostname, $disk [,$field] ); + if ( $report->get_flag($flag) ) { ... } + +The C 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: + +=over -This method returns all the information stored in the per-DLE section -for the given C<$hostname> and C. The returned value is a hash -reference to the data as it is stored in the internal data -structure. Modifying the return value will modify the values in the -C object. +=item C -=head2 my $info = $report->get_program_info($program [,$field, $default] ); +This flag is true when the driver finished +correctly. It indicates that the dump run has finished and cleaned +up. + +=item C + +This flag is set if the taper encounters an +error that forces it into degraded mode. -This method returns a reference to the data for the given C<$program>. -If the optional argument C<$field> is provided, that field in the -indicated program is returned. If the key C<$field> does not exist in -the program, then it is inserted with the value C<$default>, The -returned value is a reference to the internal C data -structure and will in turn modify the C<$report> object. +=item C -=head2 if ( $report->get_flag($flag) ) { ... } +This flag is set if amflush is run instead of planner. -This 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. +=item C + +This flag is set if the run was by amvault. + +=item C + +This flag is set when planner is run. Its value +should be opposite of C. + +=item C + +If a dump failed. + +=item C + +If a dump end in strange result. + +=item C + +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 C key to enumerate the missing results. + +=item C + +This flag is set if this is a "historical" report. It is +based on the value passed to the constructor. + +=back + +=head2 Report Data + + my $dle = $report->get_dle_info($hostname, $disk [,$field] ); + +This method returns the DLE information for the given C<$hostname> and C, +or if C<$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 C<$program>, or if +C<$field> is given, returns that field of the DLE information. See the DATA +DESCRIPTION section for the format of this information. =head1 DATA DESCRIPTION -The data in the logfile is stored in the module at -C<< $report->{data} >>. Beyond that, there are a number of subdivisions -that track both global and per-host status of the given Amanda run that -the logfile represents. +=head2 Top Level + +The data in the logfile is stored in the module at C<< $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 C and +C, as described above. -=head2 $data->{programs} + $data->{programs} the C key of the data points to a hash of global program -data, with one element per program. A number of fields are common -across all of the different programs. +information, with one element per program. See the Programs section, below. + + $data->{boguses} + +The C key refers to a list of arrayrefs of the form + + [$prog, $type, $str] + +as returned directly by C. These lines are not +in a recognized trace log format. + + $data->{disklist} + +The C 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 C<{...}> in the above contains information about the corresponding DLE. See DLEs, below. + +=head2 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: =over -=item C - the numeric timestamp at which the process was -started. +=item C -=item C