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

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