2 * Copyright (c) 2009, 2010 Zmanda, Inc. All Rights Reserved.
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.
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
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
17 * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
18 * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
25 Amanda::Logfile - manage Amanda trace logs
29 use Amanda::Logfile qw( :constants );
30 use Amanda::Config qw( :getconf config_dir_relative );
32 for my $logfile (Amanda::Logfile::find_log()) {
33 $logfile = config_dir_relative(getconf($CNF_LOGDIR)) . "/" . $logfile;
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";
42 Amanda::Logfile::close_logfile($hdl);
44 my @dumps = Amanda::Logfile::search_logfile("TapeLabel-001", "19780615", $logfile, 1);
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";
52 =head1 RAW LOGFILE ACCESS
54 This section corresponds to the C C<logfile> module.
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.
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.
69 Use these functions to read a logfile:
73 =item C<open_logfile($filename)>
75 Opens a logfile for reading, returning an opaque log file
76 handle. Returns C<undef> and sets C<$!> on failure.
78 =item C<close_logfile($handle)>
80 Closes a log file handle.
82 =item C<get_logline($handle)>
84 Returns a list as described above representing the next log line in
85 C<$handle>, or nothing at the end of the logfile.
89 =head3 Writing a "current" Logfile
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>.
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)>.
100 All of the functions in this section can be imported by name if
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:
109 make_stats($size, $duration, $orig_kb);
111 Note that C<$orig_kb> can be undefined, in which case it will not appear in
112 the statistics output.
114 =head2 Amanda::Find::find_result_t objects
116 These objects contain information about dumps, as read from logfiles.
117 Instance variables are:
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.
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
155 =head1 HIGHER-LEVEL FUNCTIONS
157 Functions in this section extract information from logfiles.
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.
168 =item C<find_all_logs([dir])>
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>.
173 =item C<find_latest_log([dir])>
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
179 =item C<search_logfile($label, $datestamp, $logfile, $add_missing_disks)>
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.
186 =item C<search_holding_disk()>
188 Return results for all holding-disk files. Results are similar to those from
191 =item C<dumps_match([@results], $hostname, $diskname, $datestamp, $level, $ok)>
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
198 =item C<dumps_match_dumpspecs([@results], [@dumpspecs], $ok)>
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.
207 All of these functions can be imported by name.
211 The following functions are available to match strings against patterns using
212 the rules described in amanda(8):
214 match_host($pat, $str);
215 match_disk($pat, $str);
216 match_datestamp($pat, $str);
217 match_level($pat, $str);
219 =head1 DEBUG LOGGING HANDLER
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:
225 use Amanda::Logfile qw( $amanda_log_trace_log );
227 Amanda::Debug::add_amanda_log_handler($amanda_log_trace_log);