Chisel

Introduction

I used to think that CATALYST_DEBUG was an all-reaching magical environment variable that somehow affected the ‘Come back Later’ screen as well as what messages were output via $c->log->...().

I’ve educated myself since then but I’ve always thought it would be an interesting exercise explicitly exploring and documenting the various behaviour under different conditions.

The Code

Code for this example can be found in the catalyst_debug branch.

After each change we run ./script/demo_server.pl with various settings and note the results.

Basic Death

What do we see if we have an action that dies?

Edit lib/Controller/Root.pm so that the index() dies (af2a29e):

sub index :Path :Args(0) {
    my ( $self, $c ) = @_;
    die 'Shot through the heart!';
    $c->response->body( $c->welcome_message );
}

Remove ‘-Debug’ plugin

What happens if we don’t force the -Debug plugin?

Edit lib/Demo.pm and remove the -Debug Catalyst plugin (4fa87c0):

use Catalyst qw/
    ConfigLoader
    Static::Simple
/;

Add StackTrace plugin

What happens if we want to see stack trace information on the Error Screen?

Edit lib/Demo.pm and add the StackTrace Catalyst plugin (20a6dd0):

use Catalyst qw/
    ConfigLoader
    Static::Simple
    StackTrace
/;

Add ErrorCatcher plugin

What happens if we add ErrorCatcher to the mix?

Edit lib/Demo.pm and add the StackTrace Catalyst plugin (95b1fc4):

use Catalyst qw/
    ConfigLoader
    Static::Simple
    StackTrace
    ErrorCatcher
/;

Test debug() with default settings

How do the variations affect logging output?

Edit lib/Controller/Root.pm and replace the death wih debugging into the log (24d7b65).

Remove debug from log levels

Do any of the options add the debug log level?

Edit lib/Demo.pm and configure the log levels after calling setup() (83eb502).

Conclusion

• -Debug isn’t necessary in a Catalyst application
• error debugging output can be controlled with either CATALYST_DEBUG or the -d script option
• Neither CATALYST_DEBUG or the -d have any affect on the behaviour of $c->log->debug(...)

Because you may wish to run your application using alternative servers you should consider using CATALYST_DEBUG as you primary method for enabling error debugging output. If you happen to my using myapp_sewrver.pl you can export this for perma-debugging, or use the -d switch as required.

If you wish to control the logging levels for $c->log->...() don’t even consider CATALYST_DEBUG or the -d switch - you’re confusing different types of debugging.

Don’t use CATALYST_DEBUG

Throughout this experiment I’ve used CATALYST_DEBUG. Ideally you’d be a thoughtful developer and use MYAPP_DEBUG to ensure that you don’t inadvertently alter the error debugging of other Catalyst based applications in mysterious and unexpected ways.

Module Versions Used

During this experiment the following modules were used:

[Catalyst::Runtime]              5.90007
[Catalyst::Devel]                1.33
[Catalyst::Plugin::StackTrace]   0.11
[Catalyst::Plugin::ErrorCatcher] 0.0.8.10