/*
 * Copyright (c) 2009-2012 Zmanda, Inc.  All Rights Reserved.
 * Copyright (c) 2013-2016 Carbonite, 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
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * 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: Carbonite Inc., 756 N Pastoria Ave
 * Sunnyvale, CA 94085, 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


%}