git.gag.com Git - debian/amanda/blob - perl/Amanda/Logfile.pod

   1 /*
   2  * Copyright (c) 2009, 2010 Zmanda, Inc.  All Rights Reserved.
   3  *
   4  * This program is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU General Public License version 2 as published
   6  * by the Free Software Foundation.
   7  *
   8  * This program is distributed in the hope that it will be useful, but
   9  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  10  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  11  * for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  16  *
  17  * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
  18  * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
  19  */
  20
  21 %perlcode %{
  22
  23 =head1 NAME
  24
  25 Amanda::Logfile - manage Amanda trace logs
  26
  27 =head1 SYNOPSIS
  28
  29   use Amanda::Logfile qw( :constants );
  30   use Amanda::Config qw( :getconf config_dir_relative );
  31
  32   for my $logfile (Amanda::Logfile::find_log()) {
  33     $logfile = config_dir_relative(getconf($CNF_LOGDIR)) . "/" . $logfile;
  34
  35     my $hdl = Amanda::Logfile::open_logfile($logfile);
  36     while (my ($type, $prog, $str) = Amanda::Logfile::get_logline($hdl)) {
  37       if ($type == $L_INFO) {
  38         my $pname = Amanda::Logfile::program_t_to_string($prog);
  39         print "Found info line from $pname: $str\n";
  40       }
  41     }
  42     Amanda::Logfile::close_logfile($hdl);
  43
  44     my @dumps = Amanda::Logfile::search_logfile("TapeLabel-001", "19780615", $logfile, 1);
  45
  46     my @matching = Amanda::Logfile::dumps_match([@dumps], "myhost", "/usr", undef, undef, 0);
  47     for my $dump (@matching) {
  48       print "$dump->{'label'}:$dump->{'filenum'} = $dump->{'hostname'}:$dump->{'disk'}\n";
  49     }
  50   }
  51
  52 =head1 RAW LOGFILE ACCESS
  53
  54 This section corresponds to the C C<logfile> module.
  55
  56 Raw access to logfiles is accomplished by opening a logfile and
  57 fetching log lines one by one via the C<get_logline> function.
  58
  59 A log line is represented by a list C<($type, $prog, $string)> where C<$type>
  60 is one of the C<L_*> constants (available in export tag C<logtype_t>), C<$prog>
  61 is one of the C<P_*> constants (available in export tag C<program_t>), and
  62 C<$str> is the remainder of the line. Both sets of constants are also available
  63 in the usual C<constants> export tag.  Both families of constants can be
  64 converted to symbolic names with C<logtype_t_to_string> and
  65 C<program_t_to_string>, respectively.
  66
  67 =head2 FUNCTIONS
  68
  69 Use these functions to read a logfile:
  70
  71 =over
  72
  73 =item C<open_logfile($filename)>
  74
  75 Opens a logfile for reading, returning an opaque log file
  76 handle. Returns C<undef> and sets C<$!> on failure.
  77
  78 =item C<close_logfile($handle)>
  79
  80 Closes a log file handle.
  81
  82 =item C<get_logline($handle)>
  83
  84 Returns a list as described above representing the next log line in
  85 C<$handle>, or nothing at the end of the logfile.
  86
  87 =back
  88
  89 To write a logfile, call C<log_add($logtype, $string)>.  On the first
  90 call, this function opens and locks C<$logdir/log>; subsequent calls
  91 just append to this file.  As such, this function is only appropriate
  92 for situations where C<amlogroll> will be invoked later to rename
  93 C<$logdir/log> to C<$logdir/log.$timestamp.$n>.
  94
  95 All of the functions in this section can be imported by name if
  96 desired.
  97
  98 =head2 Amanda::Find::find_result_t objects
  99
 100 These objects contain information about dumps, as read from logfiles.
 101 Instance variables are:
 102
 103 =over
 104
 105 =item C<timestamp>
 106
 107 =item C<hostname>
 108
 109 =item C<diskname>
 110
 111 =item C<level>
 112
 113 =item C<label>
 114
 115 =item C<filenum>
 116
 117 =item C<status>
 118
 119 =item C<partnum>
 120
 121 =item C<totalparts>
 122
 123 =item C<sec>
 124
 125 =item C<kb>
 126
 127 =back
 128
 129 Note that the format for these variables are based on that found in
 130 the logfiles.  In particular, C<timestamp> is the timestamp for the run
 131 in which the client dump took place, and not for the timestamp of the
 132 logfile.
 133
 134 =head1 HIGHER-LEVEL FUNCTIONS
 135
 136 Functions in this section extract information from logfiles.
 137
 138 =over
 139
 140 =item C<find_log()>
 141
 142 Return a list of logfiles for active tapes.  The tapelist must be loaded
 143 before this function is called (see L<Amanda::Tapelist>).  This function uses
 144 the C API which indexes logfiles with tapes.  If there is no corresponding
 145 tape, the logfile will not be found.
 146
 147 =item C<find_all_logs([dir])>
 148
 149 Return a list of all logs the configuration.  An optional directory argument
 150 can be specified, if not present, C<find_all_logs> checks C<LOGDIR>.
 151
 152 =item C<find_latest_log([dir])>
 153
 154 Returns the most recent logfile in the list of logfiles returned by
 155 C<find_all_logs>.  The optional directory argument is passed to
 156 C<find_all_logs>.
 157
 158 =item C<search_logfile($label, $datestamp, $logfile, $add_missing_disks)>
 159
 160 Return all results in C<$logfile> matching C<$label> and
 161 C<$datestamp>.  If C<$add_missing_disks> is true, then any disks in
 162 the logfile not present in the disklist are added to the disklist;
 163 otherwise, such dumps are skipped.
 164
 165 =item C<search_holding_disk()>
 166
 167 Return results for all holding-disk files.  Results are similar to those from
 168 search_logfile.
 169
 170 =item C<dumps_match([@results], $hostname, $diskname, $datestamp, $level, $ok)>
 171
 172 Return a filtered version of C<@results> containing only results that
 173 match the given expressions.  If C<$ok> is true, don't match partial
 174 results.  Note that C<$level> is given as a string, since it is a
 175 match expression.
 176
 177 =item C<dumps_match_dumpspecs([@results], [@dumpspecs], $ok)>
 178
 179 Return a filtered version of C<@results>, containing only results that match
 180 one or more of the dumpspecs.  C<$ok> is as for C<dumps_match>.  Supplying no
 181 dumpspecs will result in an empty return value.  If multiple dumpspecs match
 182 the same result, that result will be returned multiple times.
 183
 184 =back
 185
 186 All of these functions can be imported by name.
 187
 188 =head1 MATCHING
 189
 190 The following functions are available to match strings against patterns using
 191 the rules described in amanda(8):
 192
 193   match_host($pat, $str);
 194   match_disk($pat, $str);
 195   match_datestamp($pat, $str);
 196   match_level($pat, $str);
 197
 198 =head1 DEBUG LOGGING HANDLER
 199
 200 This package provides C<$amanda_log_trace_log>, which sends C<die>
 201 messages (and any C<g_error> or C<g_critical> calls from C) to the
 202 trace log.  Use it like this:
 203
 204   use Amanda::Logfile qw( $amanda_log_trace_log );
 205   # ...
 206   Amanda::Debug::add_amanda_log_handler($amanda_log_trace_log);
 207
 208 =cut
 209
 210
 211 %}