--- /dev/null
+/*
+ * Copyright (c) 2009, 2010 Zmanda, Inc. All Rights Reserved.
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 as published
+ * by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ *
+ * Contact information: Zmanda Inc., 465 S. Mathilda Ave., Suite 300
+ * Sunnyvale, CA 94085, USA, or: http://www.zmanda.com
+ */
+
+%perlcode %{
+
+=head1 NAME
+
+Amanda::Logfile - manage Amanda trace logs
+
+=head1 SYNOPSIS
+
+ use Amanda::Logfile qw( :constants );
+ use Amanda::Config qw( :getconf config_dir_relative );
+
+ for my $logfile (Amanda::Logfile::find_log()) {
+ $logfile = config_dir_relative(getconf($CNF_LOGDIR)) . "/" . $logfile;
+
+ my $hdl = Amanda::Logfile::open_logfile($logfile);
+ while (my ($type, $prog, $str) = Amanda::Logfile::get_logline($hdl)) {
+ if ($type == $L_INFO) {
+ my $pname = Amanda::Logfile::program_t_to_string($prog);
+ print "Found info line from $pname: $str\n";
+ }
+ }
+ Amanda::Logfile::close_logfile($hdl);
+
+ my @dumps = Amanda::Logfile::search_logfile("TapeLabel-001", "19780615", $logfile, 1);
+
+ my @matching = Amanda::Logfile::dumps_match([@dumps], "myhost", "/usr", undef, undef, 0);
+ for my $dump (@matching) {
+ print "$dump->{'label'}:$dump->{'filenum'} = $dump->{'hostname'}:$dump->{'disk'}\n";
+ }
+ }
+
+=head1 RAW LOGFILE ACCESS
+
+This section corresponds to the C C<logfile> module.
+
+Raw access to logfiles is accomplished by opening a logfile and
+fetching log lines one by one via the C<get_logline> function.
+
+A log line is represented by a list C<($type, $prog, $string)> where C<$type>
+is one of the C<L_*> constants (available in export tag C<logtype_t>), C<$prog>
+is one of the C<P_*> constants (available in export tag C<program_t>), and
+C<$str> is the remainder of the line. Both sets of constants are also available
+in the usual C<constants> export tag. Both families of constants can be
+converted to symbolic names with C<logtype_t_to_string> and
+C<program_t_to_string>, respectively.
+
+=head2 FUNCTIONS
+
+Use these functions to read a logfile:
+
+=over
+
+=item C<open_logfile($filename)>
+
+Opens a logfile for reading, returning an opaque log file
+handle. Returns C<undef> and sets C<$!> on failure.
+
+=item C<close_logfile($handle)>
+
+Closes a log file handle.
+
+=item C<get_logline($handle)>
+
+Returns a list as described above representing the next log line in
+C<$handle>, or nothing at the end of the logfile.
+
+=back
+
+=head3 Writing a "current" Logfile
+
+To write a logfile, call C<log_add($logtype, $string)>. On the first call,
+this function opens and locks C<$logdir/log>; subsequent calls just append to
+this file. As such, this function is only appropriate for situations where
+C<log_rename> will be invoked later to rename C<$logdir/log> to
+C<$logdir/log.$timestamp.$n>.
+
+If you need to write a log entry for another program, for example to simulate
+taper entries, call C<log_add_full($logtype, $pname, $string)>.
+
+All of the functions in this section can be imported by name if
+desired.
+
+=head3 Utilities
+
+Many trace log entries have a statistics entry in what used to be the error
+message slot, of the form C<[sec .. kb .. kps ..]>. The function C<make_stats>
+will create such an entry for you:
+
+ make_stats($size, $duration, $orig_kb);
+
+Note that C<$orig_kb> can be undefined, in which case it will not appear in
+the statistics output.
+
+=head2 Amanda::Find::find_result_t objects
+
+These objects contain information about dumps, as read from logfiles.
+Instance variables are:
+
+To rename the current logfile to a datestamped logfile, call C<log_rename($ts)>
+where C<$ts> is the write timestamp for this dump. The
+C<get_current_log_timestamp()> function will calculate this timestamp,
+returning C<undef> on error.
+
+=over
+
+=item C<timestamp>
+
+=item C<hostname>
+
+=item C<diskname>
+
+=item C<level>
+
+=item C<label>
+
+=item C<filenum>
+
+=item C<status>
+
+=item C<partnum>
+
+=item C<totalparts>
+
+=item C<sec>
+
+=item C<kb>
+
+=back
+
+Note that the format for these variables are based on that found in
+the logfiles. In particular, C<timestamp> is the timestamp for the run
+in which the client dump took place, and not for the timestamp of the
+logfile.
+
+=head1 HIGHER-LEVEL FUNCTIONS
+
+Functions in this section extract information from logfiles.
+
+=over
+
+=item C<find_log()>
+
+Return a list of logfiles for active tapes. The tapelist must be loaded
+before this function is called (see L<Amanda::Tapelist>). This function uses
+the C API which indexes logfiles with tapes. If there is no corresponding
+tape, the logfile will not be found.
+
+=item C<find_all_logs([dir])>
+
+Return a list of all logs the configuration. An optional directory argument
+can be specified, if not present, C<find_all_logs> checks C<LOGDIR>.
+
+=item C<find_latest_log([dir])>
+
+Returns the most recent logfile in the list of logfiles returned by
+C<find_all_logs>. The optional directory argument is passed to
+C<find_all_logs>.
+
+=item C<search_logfile($label, $datestamp, $logfile, $add_missing_disks)>
+
+Return all results in C<$logfile> matching C<$label> and
+C<$datestamp>. If C<$add_missing_disks> is true, then any disks in
+the logfile not present in the disklist are added to the disklist;
+otherwise, such dumps are skipped.
+
+=item C<search_holding_disk()>
+
+Return results for all holding-disk files. Results are similar to those from
+search_logfile.
+
+=item C<dumps_match([@results], $hostname, $diskname, $datestamp, $level, $ok)>
+
+Return a filtered version of C<@results> containing only results that
+match the given expressions. If C<$ok> is true, don't match partial
+results. Note that C<$level> is given as a string, since it is a
+match expression.
+
+=item C<dumps_match_dumpspecs([@results], [@dumpspecs], $ok)>
+
+Return a filtered version of C<@results>, containing only results that match
+one or more of the dumpspecs. C<$ok> is as for C<dumps_match>. Supplying no
+dumpspecs will result in an empty return value. If multiple dumpspecs match
+the same result, that result will be returned multiple times.
+
+=back
+
+All of these functions can be imported by name.
+
+=head1 DEBUG LOGGING HANDLER
+
+This package provides C<$amanda_log_trace_log>, which sends C<die>
+messages (and any C<g_error> or C<g_critical> calls from C) to the
+trace log. Use it like this:
+
+ use Amanda::Logfile qw( $amanda_log_trace_log );
+ # ...
+ Amanda::Debug::add_amanda_log_handler($amanda_log_trace_log);
+
+=cut
+
+
+%}
projects / debian / amanda / blobdiff