NAME

Exception::Reporter - a generic exception-reporting object

VERSION

version 0.004

SYNOPSIS

Achtung! This is an experimental refactoring of some long-standing internal code. It might get even more refactored. Once I've sent a few hundred thousand exceptions through it, I'll remove this warning...

First, you create a reporter. Probably you stick it someplace globally accessible, like MyApp->reporter.

my $reporter = Exception::Reporter->new({
  always_dump => { env => sub { \%ENV } },
  sender      => [
    Exception::Reporter::Sender::Email->new({
      from => 'root',
      to   => 'SysAdmins <sysadmins@example.com>',
    }),
  ],
  summarizers => [
    Exception::Reporter::Summarizer::Email->new,
    Exception::Reporter::Summarizer::File->new,
    Exception::Reporter::Summarizer::ExceptionClass->new,
    Exception::Reporter::Summarizer::Fallback->new,
  ],
});

Later, some exception has been thrown! Maybe it's an Exception::Class-based exception, or a string, or a Throwable object or who knows what.

try {
  ...
} catch {
  MyApp->reporter->report_exception(
    [
      [ exception => $_ ],
      [ request   => $current_request ],
      [ uploading => Exception::Reporter::Dumpable::File->new($filename) ],
    ],
  );
};

The sysadmins will get a nice email report with all the dumped data, and reports will thread. Awesome, right?

OVERVIEW

Exception::Reporter takes a bunch of input (the dumpables) and tries to figure out how to summarize them and build them into a report to send to somebody. Probably a human being.

It does this with two kinds of plugins: summarizers and senders.

The summarizers' job is to convert each dumpable into a simple hashref describing it. The senders' job is to take those hashrefs and send them to somebody who cares.

METHODS

new

my $reporter = Exception::Reporter->new(\%arg);

This returns a new reporter. Valid arguments are:

summarizers  - an arrayref of summarizer objects; required
senders      - an arrayref of sender objects; required
dumper       - a Exception::Reporter::Dumper used for dumping data
always_dump  - a hashref of coderefs used to generate extra dumpables
caller_level - if given, the reporter will look n frames up; see below

The always_dump hashref bears a bit more explanation. When "report_exception" is called, each entry in always_dump will be evaluated and appended to the list of given dumpables. This lets you make your reporter always include some more useful information.

...but remember! The reporter is probably doing its job in a catch block, which means that anything that might have been changed local-ly in your try block will not be the same when evaluated as part of the always_dump code. This might not matter often, but keep it in mind when setting up your reporter.

In real code, you're likely to create one Exception::Reporter object and make it globally accessible through some method. That method adds a call frame, and Exception::Reporter sometimes looks at caller to get a default. If you want to skip those intermedite call frames, pass caller_level. It will be used as the number of frames up the stack to look. It defaults to zero.

report_exception

$reporter->report_exception(\@dumpables, \%arg);

This method makes the reporter do its job: summarize dumpables and send a report.

Useful options in %arg are:

reporter    - the program or authority doing the reporting; defaults to
              the calling package

handled     - this indicates that this exception has been handled and that
              the user has not seen a terribel crash; senders might use
              this to decide who needs to get woken up

extra_rcpts - this can be an arrayref of email addresses to be used as
              extra envelope recipients by the Email sender

Each entry in @dumpables is expected to look like this:

[ $short_name, $value, \%arg ]

The short name is used for a few things, including identifying the dumps inside the report produced. It's okay to have duplicated short names.

The value can, in theory, be anything. It can be undef, any kind of object, or whatever you want to stick in a scalar. It's possible that extremely exotic values could confuse the "fallback" summarizer of last resort, but for the most part, anything goes.

The %arg entry isn't used for anything by the core libraries that ship with Exception::Reporter, but you might want to use it for your own purposes. Feel free.

The reporter will try to summarize each dumpable by asking each summarizer, in order, whether it can_summarize the dumpable. If it can, it will be asked to summarize the dumpable. The summaries are collected into a structure that looks like this:

[
  [ dumpable_short_name => \@summaries ],
  ...
]

If a given dumpable can't be dumped by any summarizer, a not-very-useful placeholder is put in its place.

The arrayref constructed is passed to the send_report method of each sender, in turn.

AUTHOR

Ricardo Signes <rjbs@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Ricardo Signes.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Exception::Reporter

perl -MCPAN -e shell
install Exception::Reporter