File Coverage

blib/lib/Exception/Reporter.pm

Criterion	Covered	Total	%
statement	56	57	98.2
branch	8	12	66.6
condition	8	15	53.3
subroutine	9	9	100.0
pod	3	4	75.0
total	84	97	86.6

use strict;
use warnings;
package Exception::Reporter 0.015;
# ABSTRACT: a generic exception-reporting object

#pod =head1 SYNOPSIS
#pod
#pod B  This is an experimental refactoring of some long-standing internal
#pod code.  It might get even more refactored.  Once I've sent a few hundred
#pod thousand exceptions through it, I'll remove this warning...
#pod
#pod First, you create a reporter.  Probably you stick it someplace globally
#pod accessible, like MyApp->reporter.
#pod
#pod   my $reporter = Exception::Reporter->new({
#pod     always_dump => { env => sub { \%ENV } },
#pod     senders     => [
#pod       Exception::Reporter::Sender::Email->new({
#pod         from => '[e-mail]',
#pod         to   => 'SysAdmins ',
#pod       }),
#pod     ],
#pod     summarizers => [
#pod       Exception::Reporter::Summarizer::Email->new,
#pod       Exception::Reporter::Summarizer::File->new,
#pod       Exception::Reporter::Summarizer::ExceptionClass->new,
#pod       Exception::Reporter::Summarizer::Fallback->new,
#pod     ],
#pod   });
#pod
#pod Later, some exception has been thrown!  Maybe it's an L-based
#pod exception, or a string, or a L object or who knows what.
#pod
#pod   try {
#pod     ...
#pod   } catch {
#pod     MyApp->reporter->report_exception(
#pod       [
#pod         [ exception => $_ ],
#pod         [ request   => $current_request ],
#pod         [ uploading => Exception::Reporter::Dumpable::File->new($filename) ],
#pod       ],
#pod     );
#pod   };
#pod
#pod The sysadmins will get a nice email report with all the dumped data, and
#pod reports will thread.  Awesome, right?
#pod
#pod =head1 OVERVIEW
#pod
#pod Exception::Reporter takes a bunch of input (the I) and tries to
#pod figure out how to summarize them and build them into a report to send to
#pod somebody.  Probably a human being.
#pod
#pod It does this with two kinds of plugins:  summarizers and senders.
#pod
#pod The summarizers' job is to convert each dumpable into a simple hashref
#pod describing it.  The senders' job is to take those hashrefs and send them to
#pod somebody who cares.
#pod
#pod =cut

use Data::GUID guid_string => { -as => '_guid_string' };

#pod =method new
#pod
#pod   my $reporter = Exception::Reporter->new(\%arg);
#pod
#pod This returns a new reporter.  Valid arguments are:
#pod
#pod   summarizers  - an arrayref of summarizer objects; required
#pod   senders      - an arrayref of sender objects; required
#pod   dumper       - a Exception::Reporter::Dumper used for dumping data
#pod   always_dump  - a hashref of coderefs used to generate extra dumpables
#pod   caller_level - if given, the reporter will look n frames up; see below
#pod
#pod The C hashref bears a bit more explanation.  When
#pod C> is called, each entry in C will be
#pod evaluated and appended to the list of given dumpables.  This lets you make your
#pod reporter always include some more useful information.
#pod
#pod I<...but remember!>  The reporter is probably doing its job in a C
#pod block, which means that anything that might have been changed C-ly in
#pod your C block will I be the same when evaluated as part of the
#pod C code.  This might not matter often, but keep it in mind when
#pod setting up your reporter.
#pod
#pod In real code, you're likely to create one Exception::Reporter object and make
#pod it globally accessible through some method.  That method adds a call frame, and
#pod Exception::Reporter sometimes looks at C to get a default.  If you want
#pod to skip those intermedite call frames, pass C.  It will be used
#pod as the number of frames up the stack to look.  It defaults to zero.
#pod
#pod =cut

sub new {
  my ($class, $arg) = @_;

  my $self = {
    summarizers  => $arg->{summarizers},
    senders      => $arg->{senders},
    dumper       => $arg->{dumper},
    always_dump  => $arg->{always_dump},
    caller_level => $arg->{caller_level} || 0,
  };

  if ($self->{always_dump}) {
    for my $key (keys %{ $self->{always_dump} }) {
      Carp::confess("non-coderef entry in always_dump: $key")
        unless ref($self->{always_dump}{$key}) eq 'CODE';
    }
  }

  $self->{dumper} ||= do {
    require Exception::Reporter::Dumper::YAML;
    Exception::Reporter::Dumper::YAML->new;
  };

  Carp::confess("entry in dumper is not an Exception::Reporter::Dumper")
    unless $self->{dumper}->isa('Exception::Reporter::Dumper');

  for my $test (qw(Summarizer Sender)) {
    my $class = "Exception::Reporter::$test";
    my $key   = "\L${test}s";

    Carp::confess("no $key given") unless $arg->{$key} and @{ $arg->{$key} };
    Carp::confess("entry in $key is not an $class")
      if grep { ! $_->isa($class) } @{ $arg->{$key} };
  }

  bless $self => $class;

  $_->register_reporter($self) for $self->_summarizers;

  return $self;
}

sub _summarizers { return @{ $_[0]->{summarizers} }; }
sub _senders     { return @{ $_[0]->{senders} }; }

sub dumper { return $_[0]->{dumper} }

#pod =method report_exception
#pod
#pod   $reporter->report_exception(\@dumpables, \%arg);
#pod
#pod This method makes the reporter do its job: summarize dumpables and send a
#pod report.
#pod
#pod Useful options in C<%arg> are:
#pod
#pod   reporter    - the program or authority doing the reporting; defaults to
#pod                 the calling package
#pod
#pod   handled     - this indicates that this exception has been handled and that
#pod                 the user has not seen a terrible crash; senders might use
#pod                 this to decide who needs to get woken up
#pod
#pod   extra_rcpts - this can be an arrayref of email addresses to be used as
#pod                 extra envelope recipients by the Email sender
#pod
#pod Each entry in C<@dumpables> is expected to look like this:
#pod
#pod   [ $short_name, $value, \%arg ]
#pod
#pod The short name is used for a few things, including identifying the dumps inside
#pod the report produced.  It's okay to have duplicated short names.
#pod
#pod The value can, in theory, be I.  It can be C, any kind of
#pod object, or whatever you want to stick in a scalar.  It's possible that
#pod extremely exotic values could confuse the "fallback" summarizer of last resort,
#pod but for the most part, anything goes.
#pod
#pod The C<%arg> entry isn't used for anything by the core libraries that ship with
#pod Exception::Reporter, but you might want to use it for your own purposes.  Feel
#pod free.
#pod
#pod The reporter will try to summarize each dumpable by asking each summarizer, in
#pod order, whether it C the dumpable.  If it can, it will be asked
#pod to C the dumpable.  The summaries are collected into a structure
#pod that looks like this:
#pod
#pod   [
#pod     [ dumpable_short_name => \@summaries ],
#pod     ...
#pod   ]
#pod
#pod If a given dumpable can't be dumped by any summarizer, a not-very-useful
#pod placeholder is put in its place.
#pod
#pod The arrayref constructed is passed to the C method of each sender,
#pod in turn.
#pod
#pod =cut

sub report_exception {
  my ($self, $dumpables, $arg) = @_;
  $dumpables ||= [];
  $arg ||= {};

  my $guid = _guid_string;

  my @caller = caller( $self->{caller_level} );
  $arg->{reporter} ||= $caller[0];

  my $summaries = $self->collect_summaries($dumpables);

  for my $sender ($self->_senders) {
    $sender->send_report(
      $summaries,
      $arg,
      {
        guid   => $guid,
        caller => \@caller,
      }
    );
  }

  return $guid;
}

#pod =method collect_summaries
#pod
#pod   $reporter->report_exception(\@dumpables);
#pod
#pod This method is used by L to convert dumpables into
#pod summaries. It may be called directly by summarizers through
#pod C<< $self->reporter->collect_summaries(\@dumpables); >> if your
#pod summarizers receive dumpables that may be handled by another summarizer. Be
#pod wary though, because you could possibly create an endless loop...
#pod
#pod =cut

sub collect_summaries {
  my ($self, $dumpables) = @_;

  my @sumz = $self->_summarizers;

  my @summaries;

  DUMPABLE: for my $dumpable (
    @$dumpables,
    map {; [ $_, $self->{always_dump}{$_}->() ] }
      sort keys %{$self->{always_dump}}
  ) {
    for my $sum (@sumz) {
      next unless $sum->can_summarize($dumpable);
      push @summaries, [ $dumpable->[0], [ $sum->summarize($dumpable) ] ];
      next DUMPABLE;
    }

    push @summaries, [
      $dumpable->[0],
      [ {
        ident => "UNKNOWN",
        body  => "the entry for <$dumpable->[0]> could not be summarized",
        mimetype => 'text/plain',
        filename => 'unknown.txt',
      } ],
    ];
  }

  return \@summaries;
}

1;

__END__