2 * Copyright (c) 2009-2012 Zmanda, Inc. All Rights Reserved.
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.
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
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
18 * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
19 * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
26 Amanda::Logfile - manage Amanda trace logs
30 use Amanda::Logfile qw( :constants );
31 use Amanda::Config qw( :getconf config_dir_relative );
33 for my $logfile (Amanda::Logfile::find_log()) {
34 $logfile = config_dir_relative(getconf($CNF_LOGDIR)) . "/" . $logfile;
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";
43 Amanda::Logfile::close_logfile($hdl);
45 my @dumps = Amanda::Logfile::search_logfile("TapeLabel-001", "19780615", $logfile, 1);
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";
53 =head1 RAW LOGFILE ACCESS
55 This section corresponds to the C C<logfile> module.
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.
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.
70 Use these functions to read a logfile:
74 =item C<open_logfile($filename)>
76 Opens a logfile for reading, returning an opaque log file
77 handle. Returns C<undef> and sets C<$!> on failure.
79 =item C<close_logfile($handle)>
81 Closes a log file handle.
83 =item C<get_logline($handle)>
85 Returns a list as described above representing the next log line in
86 C<$handle>, or nothing at the end of the logfile.
90 =head3 Writing a "current" Logfile
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>.
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)>.
101 All of the functions in this section can be imported by name if
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:
110 make_stats($size, $duration, $orig_kb);
112 Note that C<$orig_kb> can be undefined, in which case it will not appear in
113 the statistics output.
115 =head2 Amanda::Find::find_result_t objects
117 These objects contain information about dumps, as read from logfiles.
118 Instance variables are:
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.
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
156 =head1 HIGHER-LEVEL FUNCTIONS
158 Functions in this section extract information from logfiles.
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.
169 =item C<find_all_logs([dir])>
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>.
174 =item C<find_latest_log([dir])>
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
180 =item C<search_logfile($label, $datestamp, $logfile, $add_missing_disks)>
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.
187 =item C<search_holding_disk()>
189 Return results for all holding-disk files. Results are similar to those from
192 =item C<dumps_match([@results], $hostname, $diskname, $datestamp, $level, $ok)>
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
199 =item C<dumps_match_dumpspecs([@results], [@dumpspecs], $ok)>
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.
208 All of these functions can be imported by name.
210 =head1 DEBUG LOGGING HANDLER
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:
216 use Amanda::Logfile qw( $amanda_log_trace_log );
218 Amanda::Debug::add_amanda_log_handler($amanda_log_trace_log);