1# NAME
2
3Mojolicious::Plugin::NYTProf - Auto handling of Devel::NYTProf in your Mojolicious app
4
5<div>
6
7    <a href='https://travis-ci.org/Humanstate/mojolicious-plugin-nytprof?branch=master'><img src='https://travis-ci.org/Humanstate/mojolicious-plugin-nytprof.svg?branch=master' alt='Build Status' /></a>
8    <a href='https://coveralls.io/r/Humanstate/mojolicious-plugin-nytprof?branch=master'><img src='https://coveralls.io/repos/Humanstate/mojolicious-plugin-nytprof/badge.png?branch=master' alt='Coverage Status' /></a>
9</div>
10
11# VERSION
12
130.22
14
15# DESCRIPTION
16
17This plugin enables [Mojolicious](https://metacpan.org/pod/Mojolicious) to automatically generate Devel::NYTProf
18profiles and routes for your app, it has been inspired by
19[Dancer::Plugin::NYTProf](https://metacpan.org/pod/Dancer::Plugin::NYTProf)
20
21# SYNOPSIS
22
23    use Mojolicious::Lite;
24
25    plugin NYTProf => {
26      nytprof => {
27        ... # see CONFIGURATION
28      },
29    };
30
31    app->start;
32
33Or
34
35    use Mojo::Base 'Mojolicious';
36
37    ...
38
39    sub startup {
40      my $self = shift;
41
42      ...
43
44      my $mojo_config = $self->plugin('Config');
45      $self->plugin(NYTProf => $mojo_config);
46    }
47
48Then run your app. Profiles generated can be seen by visting /nytprof and reports
49will be generated on the fly when you click on a specific profile.
50
51# METHODS
52
53## register
54
55Registers the plugin with your app - this will only do something if the nytprof
56key exists in your config hash
57
58    $self->register($app, \%config);
59
60# HOOKS AND Devel::NYTProf
61
62The plugin adds hooks to control the level of profiling, Devel::NYTProf profiling
63is started using a before\_routes hook and the stopped with an around\_dispatch hook.
64
65The consequence of this is that you should see profiling only for your routes and
66rendering code and will not see most of the actual Mojolicious framework detail.
67
68The caveat with the use of hooks is that some hooks can fire out of order, and when
69asynchronous code is used in your controllers you may see incomplete/odd profiling
70behaviour - you can play around with the hook configuration to try to fix this.
71
72You can override the hooks used to control when the profiling runs, see the
73CONFIGURATION section below.
74
75# CONFIGURATION
76
77Here's what you can control in myapp.conf:
78
79    {
80      # Devel::NYTProf will only be loaded, and profiling enabled, if the nytprof
81      # key is present in your config file, so either remove it or comment it out
82      # to completely disable profiling.
83      nytprof => {
84
85        # path to your nytprofhtml script (installed as part of Devel::NYTProf
86        # distribution). the plugin will do its best to try to find this so this
87        # is optional, just set if you have a none standard path
88        nytprofhtml_path => '/path/to/nytprofhtml',
89
90        # path to store Devel::NYTProf output profiles and generated html pages.
91        # options, defaults to "/path/to/your/app/root/dir/nytprof"
92        profiles_dir => '/path/to/nytprof/profiles/'
93
94        # set this to true to allow the plugin to run when in production mode
95        # the default value is 0 so you can deploy your app to prod without
96        # having to make any changes to config/plugin register
97        allow_production => 0,
98
99        # Devel::NYTProf environment options, see the documentation at
100        # https://metacpan.org/pod/Devel::NYTProf#NYTPROF-ENVIRONMENT-VARIABLE
101        # for a complete list. N.B. you can't supply start or file as these
102        # are used internally in the plugin so will be ignored if passed
103        env => {
104          trace => 1,
105          log   => "/path/to/foo/",
106          ....
107        },
108
109        # when to enable Devel::NYTProf profiling - the pre_hook will run
110        # to enable_profile and the post_hook will run to disable_profile
111        # and finish_profile. the values show here are the defaults so you
112        # do not need to provide these options
113        #
114        # bear in mind the caveats in the Mojolicious docs regarding hooks
115        # and that they may not fire in the order you expect - this can
116        # affect the NYTProf output and cause some things not to appear
117        # (or appear in the wrong order). the defaults below should be
118        # sufficient for profiling your code, however you can change these
119        #
120        # N.B. there is nothing stopping you reversing the order of the
121        # hooks, which would cause the Mojolicious framework code to be
122        # profiled, or providing hooks that are the same or even invalid. these
123        # config options should probably be used with some care
124        pre_hook  => 'before_routes',
125        post_hook => 'around_dispatch',
126      },
127    }
128
129# nytprofhtml LOCATION
130
131The plugin does its best to find the path to your nytprofhtml executable, if
132it cannot find it then it will die with an error. This also affects testing,
133and any tests will be skipped if they cannot find nytprofhtml allowing you to
134install the plugin - you will then need to make sure to set the path in your
135config using nytprofhtml\_path
136
137# AUTHOR
138
139Lee Johnson - `leejo@cpan.org`
140
141# LICENSE
142
143This library is free software; you can redistribute it and/or modify it under
144the same terms as Perl itself. If you would like to contribute documentation
145please raise an issue / pull request:
146
147    https://github.com/Humanstate/mojolicious-plugin-nytprof
148