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 =head3 Writing a "current" Logfile
  90
  91 To write a logfile, call C<log_add($logtype, $string)>.  On the first call,
  92 this function opens and locks C<$logdir/log>; subsequent calls just append to
  93 this file.  As such, this function is only appropriate for situations where
  94 C<log_rename> will be invoked later to rename C<$logdir/log> to
  95 C<$logdir/log.$timestamp.$n>.
  96
  97 If you need to write a log entry for another program, for example to simulate
  98 taper entries, call C<log_add_full($logtype, $pname, $string)>.
  99
 100 All of the functions in this section can be imported by name if
 101 desired.
 102
 103 =head3 Utilities
 104
 105 Many trace log entries have a statistics entry in what used to be the error
 106 message slot, of the form C<[sec .. kb .. kps ..]>.  The function C<make_stats>
 107 will create such an entry for you:
 108
 109     make_stats($size, $duration, $orig_kb);
 110
 111 Note that C<$orig_kb> can be undefined, in which case it will not appear in
 112 the statistics output.
 113
 114 =head2 Amanda::Find::find_result_t objects
 115
 116 These objects contain information about dumps, as read from logfiles.
 117 Instance variables are:
 118
 119 To rename the current logfile to a datestamped logfile, call C<log_rename($ts)>
 120 where C<$ts> is the write timestamp for this dump.  The
 121 C<get_current_log_timestamp()> function will calculate this timestamp,
 122 returning C<undef> on error.
 123
 124 =over
 125
 126 =item C<timestamp>
 127
 128 =item C<hostname>
 129
 130 =item C<diskname>
 131
 132 =item C<level>
 133
 134 =item C<label>
 135
 136 =item C<filenum>
 137
 138 =item C<status>
 139
 140 =item C<partnum>
 141
 142 =item C<totalparts>
 143
 144 =item C<sec>
 145
 146 =item C<kb>
 147
 148 =back
 149
 150 Note that the format for these variables are based on that found in
 151 the logfiles.  In particular, C<timestamp> is the timestamp for the run
 152 in which the client dump took place, and not for the timestamp of the
 153 logfile.
 154
 155 =head1 HIGHER-LEVEL FUNCTIONS
 156
 157 Functions in this section extract information from logfiles.
 158
 159 =over
 160
 161 =item C<find_log()>
 162
 163 Return a list of logfiles for active tapes.  The tapelist must be loaded
 164 before this function is called (see L<Amanda::Tapelist>).  This function uses
 165 the C API which indexes logfiles with tapes.  If there is no corresponding
 166 tape, the logfile will not be found.
 167
 168 =item C<find_all_logs([dir])>
 169
 170 Return a list of all logs the configuration.  An optional directory argument
 171 can be specified, if not present, C<find_all_logs> checks C<LOGDIR>.
 172
 173 =item C<find_latest_log([dir])>
 174
 175 Returns the most recent logfile in the list of logfiles returned by
 176 C<find_all_logs>.  The optional directory argument is passed to
 177 C<find_all_logs>.
 178
 179 =item C<search_logfile($label, $datestamp, $logfile, $add_missing_disks)>
 180
 181 Return all results in C<$logfile> matching C<$label> and
 182 C<$datestamp>.  If C<$add_missing_disks> is true, then any disks in
 183 the logfile not present in the disklist are added to the disklist;
 184 otherwise, such dumps are skipped.
 185
 186 =item C<search_holding_disk()>
 187
 188 Return results for all holding-disk files.  Results are similar to those from
 189 search_logfile.
 190
 191 =item C<dumps_match([@results], $hostname, $diskname, $datestamp, $level, $ok)>
 192
 193 Return a filtered version of C<@results> containing only results that
 194 match the given expressions.  If C<$ok> is true, don't match partial
 195 results.  Note that C<$level> is given as a string, since it is a
 196 match expression.
 197
 198 =item C<dumps_match_dumpspecs([@results], [@dumpspecs], $ok)>
 199
 200 Return a filtered version of C<@results>, containing only results that match
 201 one or more of the dumpspecs.  C<$ok> is as for C<dumps_match>.  Supplying no
 202 dumpspecs will result in an empty return value.  If multiple dumpspecs match
 203 the same result, that result will be returned multiple times.
 204
 205 =back
 206
 207 All of these functions can be imported by name.
 208
 209 =head1 MATCHING
 210
 211 The following functions are available to match strings against patterns using
 212 the rules described in amanda(8):
 213
 214   match_host($pat, $str);
 215   match_disk($pat, $str);
 216   match_datestamp($pat, $str);
 217   match_level($pat, $str);
 218
 219 =head1 DEBUG LOGGING HANDLER
 220
 221 This package provides C<$amanda_log_trace_log>, which sends C<die>
 222 messages (and any C<g_error> or C<g_critical> calls from C) to the
 223 trace log.  Use it like this:
 224
 225   use Amanda::Logfile qw( $amanda_log_trace_log );
 226   # ...
 227   Amanda::Debug::add_amanda_log_handler($amanda_log_trace_log);
 228
 229 =cut
 230
 231
 232 %}