Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Catalyst::Plugin::ErroUsercContributed Perl DCatalyst::Plugin::ErrorCatcher(3)

NAME
       Catalyst::Plugin::ErrorCatcher -	Catch application errors and emit them
       somewhere

VERSION
       version 0.0.8.21

SYNOPSIS
	 use Catalyst qw/-Debug	StackTrace ErrorCatcher/;

DESCRIPTION
       This plugin allows you to do More Stuff with the	information that would
       normally	only be	seen on	the Catalyst Error Screen courtesy of the
       Catalyst::Plugin::StackTrace plugin.

   setup($c, $@)
       Prepare the plugin for use.

   finalize_error($c)
       If configured, and needed, deal with raised errors.

   my_finalize_error($c)
       This is the method that's called	by "finalize_error" when we do want to
       use ErrorCatcher	to format and emit some	information.

   emitters_init($c)
       This routine initialises	the emitters enabled in	the configuration for
       the plugin.

   append_feedback($stringref, $data)
       This is a small utility method that simplifies some of the work needed
       to add some data	to a string-reference, including some basic checks and
       initialisation.

   append_feedback_emptyline
       Add an empty-line to the	string-reference of data being built.

   append_feedback_keyvalue($ref, $key,	$value,	$keypadding)
       Add:

	   {key}: value

       to the feedback data being prepared.

       $keypadding is optional.	If omitted, defaults to	8.

   sanitise_param($value)
       Local implementation of "qquote"	in Data::Dumper	and general sanity
       checks and transformations of the data in a given piece of data.

   append_output_params($ref, $label, $params)
       Given a hashref of related items, $params, and a	$label for the
       grouping, add sensibly formatted	output to the feedback data being
       constructed.

CONFIGURATION
       The plugin is configured	in a similar manner to other Catalyst plugins:

	 <Plugin::ErrorCatcher>
	     enable		   1
	     context		   5
	     always_log		   0
	     include_session	   0
	     user_identified_by	   username

	     emit_module	   A::Module
	 </Plugin::ErrorCatcher>

       enable
	   Setting this	to true	forces the module to work its voodoo.

	   It's	also enabled if	the value is unset and you're running Catalyst
	   in debug-mode.

       context
	   When	there is stack-trace information to share, how many lines of
	   context to show around the line that	caused the error.

       emit_module
	   This	specifies which	module to use for custom output	behaviour.

	   You can chain multiple modules by specifying	a line in the config
	   for each module you'd like used:

	       emit_module A::Module
	       emit_module Another::Module
	       emit_module Yet::Another::Module

	   If none are specified, or all that are specified fail, the default
	   behaviour is	to log the prepared message at the INFO	level via
	   "$c->log()".

	   For details on how to implement a custom emitter see	"CUSTOM	EMIT
	   CLASSES" in this documentation.

       always_log
	   The default plugin behaviour	when using one or more emitter modules
	   is to suppress the info log message if one or more of them
	   succeeded.

	   If you wish to log the information, via "$c->log()" then set	this
	   value to 1.

       include_session
	   The default behaviour is to suppress	potentially sensitive and
	   revealing session-data in the error report.

	   If you feel that this information is	useful in your investigations
	   set the value to true.

	   When	set to 1 the report will include a "Data::Dump::pp()"
	   representation of the request's session.

       user_identified_by
	   If there's a	logged-in user use the specified value as the method
	   to identify the user.

	   If the specified value is invalid the module	defaults to using id.

	   If unspecified the value defaults to	id.

STACKTRACE IN REPORTS WHEN NOT RUNNING IN DEBUG	MODE
       It is possible to run your application in non-Debug mode, and still
       have errors reported with a stack-trace.

       Include the StackTrace and ErrorCatcher plugins in MyApp.pm:

	 use Catalyst qw<
	   ErrorCatcher
	   StackTrace
	 >;

       Set up your "myapp.conf"	to include the following:

	 <stacktrace>
	   enable      1
	 </stacktrace>

	 <Plugin::ErrorCatcher>
	   enable      1
	   # include other options here
	 <Plugin::ErrorCatcher>

       Any exceptions should now show your user	the "Please come back later"
       screen whilst still capturing and emitting a report with	stack-trace.

PROVIDED EMIT CLASSES
   Catalyst::Plugin::ErrorCatcher::Email
       This module uses	MIME::Lite to send the prepared	output to a specified
       email address.

       See Catalyst::Plugin::ErrorCatcher::Email for usage and configuration
       details.

CUSTOM EMIT CLASSES
       A custom	emit class takes the following format:

	 package A::Module;
	 # vim:	ts=8 sts=4 et sw=4 sr sta
	 use strict;
	 use warnings;

	 sub emit {
	   my ($class, $c, $output) = @_;

	   $c->log->info(
	     'IGNORING OUTPUT FROM Catalyst::Plugin::ErrorCatcher'
	   );

	   return;
	 }

	 1;
	 __END__

       The only	requirement is that you	have a sub called "emit".

       "Catalyst::Plugin::ErrorCatcher"	passes the following parameters	in the
       call to "emit()":

       $class
	   The package name

       $c  A Context object

       $output
	   The processed output	from "Catalyst::Plugin::ErrorCatcher"

       If you want to use the original error message you should	use:

	 my @error = @{	$c->error };

       You may use and abuse any Catalyst methods, or other Perl modules as
       you see fit.

KNOWN ISSUES
       BODY tests failing (Catalyst >=5.90008)
	   Summary:
	   https://github.com/chiselwright/catalyst-plugin-errorcatcher/pull/1

	   Bug report: https://rt.cpan.org/Public/Bug/Display.html?id=75607

SEE ALSO
       Catalyst, Catalyst::Plugin::StackTrace

THANKS
       The authors of Catalyst::Plugin::StackTrace, from which a lot of	code
       was used.

       Ash Berlin for guiding me in the	right direction	after a	known hacky
       first implementation.

       # vim: ts=8 sts=4 et sw=4 sr sta

AUTHOR
       Chisel <chisel@chizography.net>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2015 by Chisel Wright.

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

CONTRIBUTORS
       o   Chisel Wright <chisel@chizography.net>

       o   Fitz	Elliott	<fitz.elliott@gmail.com>

       o   Mohammad S Anwar <mohammad.anwar@yahoo.com>

       o   Tim Bunce <tim@tigerlms.com>

perl v5.32.1			  2016-01-18 Catalyst::Plugin::ErrorCatcher(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | CONFIGURATION | STACKTRACE IN REPORTS WHEN NOT RUNNING IN DEBUG MODE | PROVIDED EMIT CLASSES | CUSTOM EMIT CLASSES | KNOWN ISSUES | SEE ALSO | THANKS | AUTHOR | COPYRIGHT AND LICENSE | CONTRIBUTORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Catalyst::Plugin::ErrorCatcher&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help