3 Catalyst::Manual::Tutorial::07_Debugging - Catalyst Tutorial - Chapter 7: Debugging
8 This is B<Chapter 7 of 10> for the Catalyst tutorial.
10 L<Tutorial Overview|Catalyst::Manual::Tutorial>
16 L<Introduction|Catalyst::Manual::Tutorial::01_Intro>
20 L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
24 L<More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>
28 L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>
32 L<Authentication|Catalyst::Manual::Tutorial::05_Authentication>
36 L<Authorization|Catalyst::Manual::Tutorial::06_Authorization>
44 L<Testing|Catalyst::Manual::Tutorial::08_Testing>
48 L<Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
52 L<Appendices|Catalyst::Manual::Tutorial::10_Appendices>
59 This chapter of the tutorial takes a brief look at the primary options
60 available for troubleshooting Catalyst applications.
62 Note that when it comes to debugging and troubleshooting, there are two
69 Fans of C<log> and C<print> statements embedded in the code.
73 Fans of interactive debuggers.
77 Catalyst is able to easily accommodate both styles of debugging.
82 Folks in the former group can use Catalyst's C<$c-E<gt>log> facility.
83 (See L<Catalyst::Log> for more detail.) For example, if you add the
84 following code to a controller action method:
86 $c->log->info("Starting the foreach loop here");
88 $c->log->debug("Value of \$id is: ".$id);
90 Then the Catalyst development server will display your message along
91 with the other debug output. To accomplish the same thing in a TT
94 [% c.log.debug("This is a test log message") %]
96 As with many other logging facilities, a method is defined for each of
97 the following "logging levels" (in increasing order of
106 You can also use L<Data::Dumper> in both Catalyst code
107 (C<use Data::Dumper; $c-E<gt>log-E<gt>debug("\$var is: ".Dumper($var));)>)
108 and TT templates (C<[% Dumper.dump(book) %]>.
110 B<NOTE:> Whether you are a logging fanatic or not, we strongly recommend
111 that you take advantage of L<Log::Log4perl> or L<Log::Dispatch>. It's
112 easy to use L<Catalyst::Log> with either of these and they will provide
113 a huge amount of extra functionality that you will want in virtually
114 every production application you run or support.
117 =head1 RUNNING CATALYST UNDER THE PERL DEBUGGER
119 Members of the interactive-debugger fan club will also be at home with
120 Catalyst applications. One approach to this style of Perl debugging is
121 to embed breakpoints in your code. For example, open
122 C<lib/MyApp/Controller/Books.pm> in your editor and add the
123 C<DB::single=1> line as follows inside the C<list> method (I like to
124 "left-justify" my debug statements so I don't forget to remove them, but
125 you can obviously indent them if you prefer):
128 # Retrieve the usual Perl OO '$self' for this object. $c is the Catalyst
129 # 'Context' that's used to 'glue together' the various components
130 # that make up the application
135 # Retrieve all of the book records as book model objects and store in the
136 # stash where they can be accessed by the TT template
137 $c->stash->{books} = [$c->model('DB::Book')->all];
139 # Set the TT template to use. You will almost always want to do this
140 # in your action methods.
141 $c->stash->{template} = 'books/list.tt2';
144 This causes the Perl Debugger to enter "single step mode" when this
145 command is encountered (it has no effect when Perl is run without the
148 B<NOTE:> The C<DB> here is the Perl Debugger, not the DB model.
150 If you haven't done it already, enable SQL logging as before:
152 $ export DBIC_TRACE=1
154 To now run the Catalyst development server under the Perl debugger,
155 simply prepend C<perl -d> to the front of C<script/myapp_server.pl>:
157 $ perl -d script/myapp_server.pl
159 This will start the interactive debugger and produce output similar to:
161 $ perl -d script/myapp_server.pl
163 Loading DB routines from perl5db.pl version 1.3
164 Editor support available.
166 Enter h or `h h' for help, or `man perldebug' for more help.
168 main::(script/myapp_server.pl:16): my $debug = 0;
172 Press the C<c> key and hit C<Enter> to continue executing the Catalyst
173 development server under the debugger. Although execution speed will be
174 slightly slower than normal, you should soon see the usual Catalyst
175 startup debug information.
177 Now point your browser to L<http://localhost:3000/books/list> and log
178 in. Once the breakpoint is encountered in the
179 C<MyApp::Controller::list> method, the console session running the
180 development server will drop to the Perl debugger prompt:
182 MyApp::Controller::Books::list(/root/MyApp/script/../lib/MyApp/Controller/Books.pm:48):
183 48: $c->stash->{books} = [$c->model('DB::Book')->all];
187 You now have the full Perl debugger at your disposal. First use the
188 C<next> feature by typing C<n> to execute the C<all> method on the Book
189 model (C<n> jumps over method/subroutine calls; you can also use C<s> to
190 C<single-step> into methods/subroutines):
193 SELECT me.id, me.title, me.rating, me.created, me.updated FROM book me:
194 MyApp::Controller::Books::list(/root/MyApp/script/../lib/MyApp/Controller/Books.pm:53):
195 53: $c->stash->{template} = 'books/list.tt2';
199 This takes you to the next line of code where the template name is set.
200 Notice that because we enabled C<DBIC_TRACE=1> earlier, SQL debug output
201 also shows up in the development server debug information.
203 Next, list the methods available on our C<Book> model:
205 DB<1> m $c->model('DB::Book')
209 __result_class_accessor
210 __source_handle_accessor
216 <lines removed for brevity>
220 We can also play with the model directly:
222 DB<2> x ($c->model('DB::Book')->all)[1]->title
223 SELECT me.id, me.title, me.rating, me.created, me.updated FROM book me:
224 0 'TCP/IP Illustrated, Volume 1'
226 This uses the Perl debugger C<x> command to display the title of a book.
228 Next we inspect the C<books> element of the Catalyst C<stash> (the C<4>
229 argument to the C<x> command limits the depth of the dump to 4 levels):
231 DB<3> x 4 $c->stash->{books}
233 0 MyApp::Model::DB::Book=HASH(0xb8e702c)
234 '_column_data' => HASH(0xb8e5e2c)
235 'created' => '2009-05-08 10:19:46'
238 'title' => 'CCSP SNRS Exam Certification Guide'
239 'updated' => '2009-05-08 10:19:46'
241 <lines removed for brevity>
243 Then enter the C<c> command to continue processing until the next
244 breakpoint is hit (or the application exits):
247 SELECT author.id, author.first_name, author.last_name FROM ...
249 Finally, press C<Ctrl+C> to break out of the development server.
250 Because we are running inside the Perl debugger, you will drop to the
253 ^CCatalyst::Engine::HTTP::run(/usr/local/share/perl/5.10.0/Catalyst/Engine/HTTP.pm:260):
254 260: while ( accept( Remote, $daemon ) ) {
258 Finally, press C<q> to exit the debugger and return to your OS shell
264 For more information on using the Perl debugger, please see C<perldebug>
265 and C<perldebtut>. For those daring souls out there, you can dive down
266 even deeper into the magical depths of this fine debugger by checking
269 You can also type C<h> or C<h h> at the debugger prompt to view the
270 built-in help screens.
272 For an excellent book covering all aspects of the Perl debugger, we
273 highly recommend reading 'Pro Perl Debugging' by Richard Foley.
275 Oh yeah, before you forget, be sure to remove the C<DB::single=1> line
276 you added above in C<lib/MyApp/Controller/Books.pm>.
278 =head1 DEBUGGING MODULES FROM CPAN
280 Although the techniques discussed above work well for code you are
281 writing, what if you want to use print/log/warn messages or set
282 breakpoints in code that you have installed from CPAN (or in module that
283 ship with Perl)? One helpful approach is to place a copy of the module
284 inside the C<lib> directory of your Catalyst project. When Catalyst
285 loads, it will load from inside your C<lib> directory first, only
286 turning to the global modules if a local copy cannot be found. You can
287 then make modifications such as adding a C<$DB::single=1> to the local
288 copy of the module without risking the copy in the original location.
289 This can also be a great way to "locally override" bugs in modules while
290 you wait for a fix on CPAN.
292 Matt Trout has suggested the following shortcut to create a local copy
293 of an installed module:
295 mkdir -p lib/Module; cp `perldoc -l Module::Name` lib/Module/
297 Note: If you are following along in Debian 6 or Ubuntu, you will need to
298 install the C<perl-doc> package to use the C<perldoc> command. Use
299 C<sudo aptitude install perl-doc> to do that.
301 For example, you could make a copy of
302 L<Catalyst::Plugin::Authentication> with the following command:
304 mkdir -p lib/Catalyst/Plugin; cp \
305 `perldoc -l Catalyst::Plugin::Authentication` lib/Catalyst/Plugin
307 You can then use the local copy inside your project to place logging
308 messages and/or breakpoints for further study of that module.
310 B<Note:> Matt has also suggested the following tips for Perl debugging:
316 Check the version of an installed module:
318 perl -M<mod_name> -e 'print "$<mod_name>::VERSION\n"'
322 $ perl -MCatalyst::Plugin::Authentication -e \
323 'print $Catalyst::Plugin::Authentication::VERSION;'
326 and if you are using bash aliases:
328 alias pmver="perl -le '\$m = shift; eval qq(require \$m) \
329 or die qq(module \"\$m\" is not installed\\n); \
334 Check if a modules contains a given method:
336 perl -MModule::Name -e 'print Module::Name->can("method");'
340 $ perl -MCatalyst::Plugin::Authentication -e \
341 'print Catalyst::Plugin::Authentication->can("user");'
344 If the method exists, the Perl C<can> method returns a coderef.
345 Otherwise, it returns undef and nothing will be printed.
352 If you run into issues during the rendering of your template, it might
353 be helpful to enable TT C<DEBUG> options. You can do this in a Catalyst
354 environment by adding a C<DEBUG> line to the C<__PACKAGE__->config>
355 declaration in C<lib/MyApp/View/HTML.pm>:
357 __PACKAGE__->config({
358 TEMPLATE_EXTENSION => '.tt2',
362 There are a variety of options you can use, such as 'undef', 'all',
363 'service', 'context', 'parser' and 'provider'. See
364 L<Template::Constants> for more information (remove the C<DEBUG_>
365 portion of the name shown in the TT docs and convert to lower case for
366 use inside Catalyst).
368 B<NOTE:> B<Please be sure to disable TT debug options before continuing
369 with the tutorial> (especially the 'undef' option -- leaving this
370 enabled will conflict with several of the conventions used by this
371 tutorial to leave some variables undefined on purpose).
376 You can jump to the next chapter of the tutorial here:
377 L<Testing|Catalyst::Manual::Tutorial::08_Testing>
382 Kennedy Clark, C<hkclark@gmail.com>
384 Feel free to contact the author for any errors or suggestions, but the
385 best way to report issues is via the CPAN RT Bug system at
386 L<https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.
388 Copyright 2006-2011, Kennedy Clark, under the
389 Creative Commons Attribution Share-Alike License Version 3.0
390 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).