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 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>.
95 All of the functions in this section can be imported by name if
98 =head2 Amanda::Find::find_result_t objects
100 These objects contain information about dumps, as read from logfiles.
101 Instance variables are:
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
134 =head1 HIGHER-LEVEL FUNCTIONS
136 Functions in this section extract information from logfiles.
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.
147 =item C<find_all_logs([dir])>
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>.
152 =item C<find_latest_log([dir])>
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
158 =item C<search_logfile($label, $datestamp, $logfile, $add_missing_disks)>
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.
165 =item C<search_holding_disk()>
167 Return results for all holding-disk files. Results are similar to those from
170 =item C<dumps_match([@results], $hostname, $diskname, $datestamp, $level, $ok)>
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
177 =item C<dumps_match_dumpspecs([@results], [@dumpspecs], $ok)>
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.
186 All of these functions can be imported by name.
190 The following functions are available to match strings against patterns using
191 the rules described in amanda(8):
193 match_host($pat, $str);
194 match_disk($pat, $str);
195 match_datestamp($pat, $str);
196 match_level($pat, $str);
198 =head1 DEBUG LOGGING HANDLER
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:
204 use Amanda::Logfile qw( $amanda_log_trace_log );
206 Amanda::Debug::add_amanda_log_handler($amanda_log_trace_log);