Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 257 lines (183 sloc) 9.126 kB
30473fb initial commit
Marcel Gruenauer authored
1 # NAME
2
2199eef added miyagawa to authors; releng
Marcel Gruenauer authored
3 Plack::Middleware::Debug - display information about the current request/response
30473fb initial commit
Marcel Gruenauer authored
4
5 # SYNOPSIS
6
7c8cf47 updated READMEs
Marcel Gruenauer authored
7 # app.psgi
8
9 use Plack::Builder;
10
11 my $app = sub {
12 return [ 200, [ 'Content-Type' => 'text/html' ],
13 [ '<body>Hello World</body>' ] ];
14 };
15
16 builder {
17 enable 'Debug';
18 $app;
19 };
20
21
30473fb initial commit
Marcel Gruenauer authored
22
23 # DESCRIPTION
24
7c8cf47 updated READMEs
Marcel Gruenauer authored
25 The debug middleware offers a configurable set of panels that displays
26 information about the current request and response. The information is
27 generated only for responses with a status of 200 (`OK`) and a
4fd5912 Checking in changes prior to tagging of version 0.02. Changelog diff…
Marcel Gruenauer authored
28 `Content-Type` that contains `text/html` and is embedded in the HTML that is
10752fe regenerated aux files
Marcel Gruenauer authored
29 sent back to the browser. Also the code is injected directly before the `</body>` tag so if there is no such tag, the information will not be
30 injected.
7c8cf47 updated READMEs
Marcel Gruenauer authored
31
a6fd915 regenerated READMEs
Marcel Gruenauer authored
32 To enable the middleware, just use [Plack::Builder](http://search.cpan.org/perldoc?Plack::Builder) as usual in your `.psgi`
33 file:
34
35 use Plack::Builder;
36
37 builder {
10752fe regenerated aux files
Marcel Gruenauer authored
38 enable 'Debug', panels => [ qw(DBITrace PerlConfig) ];
a6fd915 regenerated READMEs
Marcel Gruenauer authored
39 $app;
40 };
41
15a0308 regenerated aux files
Marcel Gruenauer authored
42 The `Debug` middleware takes an optional `panels` argument whose value is
239c9a0 nav_title() defaults to title() now, so no need override for most pan…
Marcel Gruenauer authored
43 expected to be a reference to an array of panel specifications. If given,
44 only those panels will be enabled. If you don't pass a `panels`
45 argument, the default list of panels - `Environment`, `Response`,
46 `Timer` and `Memory` - will be enabled, each with their default settings.
15a0308 regenerated aux files
Marcel Gruenauer authored
47
239c9a0 nav_title() defaults to title() now, so no need override for most pan…
Marcel Gruenauer authored
48 Each panel specification can take one of three forms:
15a0308 regenerated aux files
Marcel Gruenauer authored
49
239c9a0 nav_title() defaults to title() now, so no need override for most pan…
Marcel Gruenauer authored
50 - A string
51
52 This is interpreted as the base name of a panel in the
53 `Plack::Middeware::Debug::` namespace. The panel class is loaded and a panel
54 object is created with its default settings.
55
56 - An array reference
57
58 If you need to pass arguments to the panel object as it is created, use this
59 form. The first element of the array reference has to be the panel base name.
60 The remaining elements are key/value pairs to be passed to the panel.
61
62 Not all panels take extra arguments. But the `DBITrace` panel, for example,
63 takes an optional `level` argument to specify the desired trace level.
64
65 For example:
15a0308 regenerated aux files
Marcel Gruenauer authored
66
67 builder {
68 enable 'Debug', panels =>
69 [ qw(Environment Response Timer Memory),
70 [ 'DBITrace', level => 2 ]
71 ];
72 $app;
73 };
a6fd915 regenerated READMEs
Marcel Gruenauer authored
74
239c9a0 nav_title() defaults to title() now, so no need override for most pan…
Marcel Gruenauer authored
75 - An object
76
77 You can also pass panel objects directly to the `Debug` middleware. This
78 might be useful if you have custom debug panels in your framework or web
79 application.
80
7c8cf47 updated READMEs
Marcel Gruenauer authored
81 # PANELS
82
2199eef added miyagawa to authors; releng
Marcel Gruenauer authored
83 - `DBITrace`
7c8cf47 updated READMEs
Marcel Gruenauer authored
84
85 Display DBI trace information. See [Plack::Middleware::Debug::DBITrace](http://search.cpan.org/perldoc?Plack::Middleware::Debug::DBITrace).
86
2199eef added miyagawa to authors; releng
Marcel Gruenauer authored
87 - `Environment`
7c8cf47 updated READMEs
Marcel Gruenauer authored
88
89 Displays the PSGI environment from the request. See
90 [Plack::Middleware::Debug::Environment](http://search.cpan.org/perldoc?Plack::Middleware::Debug::Environment).
91
2199eef added miyagawa to authors; releng
Marcel Gruenauer authored
92 - `Memory`
7c8cf47 updated READMEs
Marcel Gruenauer authored
93
94 Displays memory usage before the request and after the response. See
95 [Plack::Middleware::Debug::Memory](http://search.cpan.org/perldoc?Plack::Middleware::Debug::Memory).
96
2199eef added miyagawa to authors; releng
Marcel Gruenauer authored
97 - `ModuleVersions`
7c8cf47 updated READMEs
Marcel Gruenauer authored
98
99 Displays the loaded modules and their versions. See
100 [Plack::Middleware::Debug::ModuleVersions](http://search.cpan.org/perldoc?Plack::Middleware::Debug::ModuleVersions).
101
2199eef added miyagawa to authors; releng
Marcel Gruenauer authored
102 - `PerlConfig`
7c8cf47 updated READMEs
Marcel Gruenauer authored
103
104 Displays the configuration information of the Perl interpreter itself. See
105 [Plack::Middleware::Debug::PerlConfig](http://search.cpan.org/perldoc?Plack::Middleware::Debug::PerlConfig)
106
2199eef added miyagawa to authors; releng
Marcel Gruenauer authored
107 - `Response`
7c8cf47 updated READMEs
Marcel Gruenauer authored
108
109 Displays the status code and response headers. See
110 [Plack::Middleware::Debug::Response](http://search.cpan.org/perldoc?Plack::Middleware::Debug::Response).
111
2199eef added miyagawa to authors; releng
Marcel Gruenauer authored
112 - `Timer`
7c8cf47 updated READMEs
Marcel Gruenauer authored
113
114 Displays how long the request took. See [Plack::Middleware::Debug::Timer](http://search.cpan.org/perldoc?Plack::Middleware::Debug::Timer).
30473fb initial commit
Marcel Gruenauer authored
115
239c9a0 nav_title() defaults to title() now, so no need override for most pan…
Marcel Gruenauer authored
116 - `CatalystLog`
117
118 In a Catalyst application, this panel displays the Catalyst log output. See
119 [Plack::Middleware::Debug::CatalystLog](http://search.cpan.org/perldoc?Plack::Middleware::Debug::CatalystLog).
120
121 # HOW TO WRITE YOUR OWN DEBUG PANEL
122
123 The `Debug` middleware is designed to be easily extensible. You might want to
124 write a custom debug panel for your framework or for your web application.
125 Let's look at the anatomy of the `Timer` debug panel. Here is the code from
126 that panel:
127
128 package Plack::Middleware::Debug::Timer;
129 use 5.008;
130 use strict;
131 use warnings;
132 use Time::HiRes qw(gettimeofday tv_interval);
133 use Plack::Util::Accessor qw(start_time elapsed);
134 use parent qw(Plack::Middleware::Debug::Base);
135 our $VERSION = '0.03';
136
137 sub nav_subtitle {
138 my $self = shift;
139 $self->format_elapsed;
140 }
141
142 sub format_elapsed {
143 my $self = shift;
144 sprintf '%s s', $self->elapsed;
145 }
146
147 sub format_time {
148 my ($self, $time) = @_;
149 my ($sec, $min, $hour, $mday, $mon, $year) = (localtime($time->[0]));
150 sprintf "%04d.%02d.%02d %02d:%02d:%02d.%d", $year + 1900, $mon + 1, $mday,
151 $hour, $min, $sec, $time->[1];
152 }
153
154 sub process_request {
155 my ($self, $env) = @_;
156 $self->start_time([gettimeofday]);
157 }
158
159 sub process_response {
160 my ($self, $res, $env) = @_;
161 my $end_time = [gettimeofday];
162 $self->elapsed(tv_interval $self->start_time, $end_time);
163 $self->content(
164 $self->render_list_pairs(
165 [ Start => $self->format_time($self->start_time),
166 End => $self->format_time($end_time),
167 Elapsed => $self->format_elapsed,
168 ]
169 )
170 );
171 }
172
173 To write a new debug panel, place it in the `Plack::Middleware::Debug::`
174 namespace. In our example, the `Timer` panel lives in the
175 `Plack::Middleware::Debug::Timer` package.
176
177 A panel should subclass [Plack::Middleware::Debug::Base](http://search.cpan.org/perldoc?Plack::Middleware::Debug::Base). It provides a lot
178 of methods that the `Debug` middleware expects a panel to have and provides
179 some sensible defaults for others, so you only need to override what is
180 specific to your custom panel.
181
182 The panels' title - which appears at the top left when the panel is active -
183 and its navigation title - which appears in the navigation bar on the right
184 side - are set automatically from the panel's base name - `Timer` in our
185 case. This is a useful for default for us, so we don't need to override these
186 methods.
187
188 The panels' navigation subtitle, which appears in the navigation bar
189 underneath the panel title in smaller letters, is empty by default. For the
190 `Timer` panel, we would like to show the total time elapsed so the user can
191 get the quick overview without having to activate the panel. So we override
192 the `nav_subtitle()` method.
193
194 How do we know how much time elapsed for the request? We have to take the time
195 when the request comes in, and again when the response goes out. So we
196 override the `process_request()` and `process_response()` methods. In
197 `process_request()` we just store the current time. To generate the accessors
198 for any attributes our panel might need we use [Plack::Util::Accessor](http://search.cpan.org/perldoc?Plack::Util::Accessor).
199
200 In `process_response()` we take the time again, determine how much time has
201 elapsed, store that information in an accessor so `sub_navtitle()` can return
202 it when asked by the template, then we actually render the template with our
203 data and store it in `content()`.
204
205 When the HTML, CSS and JavaScript are generated and injected by the `Debug`
206 middleware, it will ask all panels whether they have any content. If so, the
207 actual panel is generated. If not, then just an inactive navigation bar entry
208 is generated. Having data in the panel's `content` attribute is the sign
209 that the `Debug` middleware looks for.
210
211 In our `Timer` example we want to list three key/value pairs: the start time,
212 the end time and the elapsed time. We use the `render_list_pairs()` method
213 to place the pairs in the order we want. There is also a `render_hash()`
214 method, but it would sort the hash keys, and this is not what we want.
215
216 With this our `Timer` debug panel is finished. Now we can use it in the
217 `enable 'Debug'` call like any other debug panel.
218
30473fb initial commit
Marcel Gruenauer authored
219 # BUGS AND LIMITATIONS
220
221 No bugs have been reported.
222
223 Please report any bugs or feature requests through the web interface at
224 <http://rt.cpan.org>.
225
226 # INSTALLATION
227
228 See perlmodinstall for information and options on installing Perl modules.
229
230 # AVAILABILITY
231
232 The latest version of this module is available from the Comprehensive Perl
4fd5912 Checking in changes prior to tagging of version 0.02. Changelog diff…
Marcel Gruenauer authored
233 Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find a CPAN site
234 near you. Or see <http://search.cpan.org/dist/Plack-Middleware-Debug/>.
30473fb initial commit
Marcel Gruenauer authored
235
4fd5912 Checking in changes prior to tagging of version 0.02. Changelog diff…
Marcel Gruenauer authored
236 The development version lives at
237 <http://github.com/hanekomu/plack-middleware-debug/>. Instead of sending
238 patches, please fork this project using the standard git and github
239 infrastructure.
30473fb initial commit
Marcel Gruenauer authored
240
241 # AUTHORS
242
243 Marcel Gr&uuml;nauer, `<marcel@cpan.org>`
244
2199eef added miyagawa to authors; releng
Marcel Gruenauer authored
245 Tatsuhiko Miyagawa, `<miyagawa@bulknews.net>`
246
30473fb initial commit
Marcel Gruenauer authored
247 # COPYRIGHT AND LICENSE
248
249 Copyright 2009 by Marcel Gr&uuml;nauer
250
251 This library is free software; you can redistribute it and/or modify
7c8cf47 updated READMEs
Marcel Gruenauer authored
252 it under the same terms as Perl itself.
253
254 # SEE ALSO
255
256 The debug middleware is heavily influenced (that is, adapted from) the Django
257 Debug Toolbar - see <http://github.com/robhudson/django-debug-toolbar>.
Something went wrong with that request. Please try again.