8000 minor #10970 Merged some profiler docs into a single main Profiler ar… · symfony/symfony-docs@f2adf5d · GitHub
[go: up one dir, main page]
Skip to content

Commit f2adf5d

Browse files
javiereguiluzjaviereguiluz
committed
minor #10970 Merged some profiler docs into a single main Profiler article (javiereguiluz)
This PR was squashed before being merged into the 4.2 branch (closes #10970). Discussion ---------- Merged some profiler docs into a single main Profiler article Instead of an empty Profiler page (https://symfony.com/doc/current/profiler.html) and some links to micro-articles ... this PR proposes to create a reference article about the Profiler and merge most of those micro-articles into it. Commits ------- 2b3384e Merged some profiler docs into a single main Profiler article
2 parents 63ccd9d + 2b3384e commit f2adf5d

File tree

7 files changed

+208
-168
lines changed

7 files changed

+208
-168
lines changed

‎_build/redirection_map

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -405,3 +405,6 @@
405405
/console/logging /console
406406
/reference/forms/twig_reference /form/form_customization
407407
/form/rendering /form/form_customization
408+
/profiler/matchers /profiler
409+
/profiler/profiling_data /profiler
410+
/profiler/wdt_follow_ajax /profiler

‎_images/profiler/web-interf 8000 ace.png

73.9 KB
Loading

‎components/stopwatch.rst

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -63,9 +63,8 @@ Symfony Profiler tool uses categories to nicely color-code different events.
6363

6464
.. tip::
6565

66-
When you want to show events in the Symfony profiler, autowire
67-
``Symfony\Component\Stopwatch\Stopwatch`` into your service. Each category
68-
is shown on a separate line.
66+
Read :ref:`this article <profiler-timing-execution>` to learn more about
67+
integrating the Stopwatch component into the Symfony profiler.
6968

7069
Periods
7170
-------

‎profiler.rst

Lines changed: 203 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,8 @@ Profiler
22
========
33

44
The profiler is a powerful **development tool** that gives detailed information
5-
about the execution of any request.
6-
7-
**Never** enable the profiler in production environments as it will lead to
8-
major security vulnerabilities in your project.
5+
about the execution of any request. **Never** enable the profiler in production
6+
environments as it will lead to major security vulnerabilities in your project.
97

108
Installation
119
------------
@@ -17,10 +15,207 @@ install the profiler before using it:
1715
1816
$ composer require --dev symfony/profiler-pack
1917
18+
Now browse any page of your application in the development environment to let
19+
the profiler collect information. Then, click on any element of the debug
20+
toolbar injected at the bottom of your pages to open the web interface of the
21+
Symfony Profiler, which will look like this:
22+
23+
.. image:: /_images/profiler/web-interface.png
24+
:align: center
25+
:class: with-browser
26+
27+
Accessing Profiling Data Programmatically
28+
-----------------------------------------
29+
30+
Most of the times, the profiler information is accessed and analyzed using its
31+
web-based interface. However, you can also retrieve profiling information
32+
programmatically thanks to the methods provided by the ``profiler`` service.
33+
34+
When the response object is available, use the
35+
:method:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler::loadProfileFromResponse`
36+
method to access to its associated profile::
37+
38+
// ... $profiler is the 'profiler' service
39+
$profile = $profiler->loadProfileFromResponse($response);
40+
41+
When the profiler stores data about a request, it also associates a token with it;
42+
this token is available in the ``X-Debug-Token`` HTTP header of the response.
43+
Using this token, you can access the profile of any past response thanks to the
44+
:method:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler::loadProfile` method::
45+
46+
$token = $response->headers->get('X-Debug-Token');
47+
$profile = $profiler->loadProfile($token);
48+
49+
.. tip::
50+
51+
When the profiler is enabled but not the web debug toolbar, inspect the page
52+
with your browser's developer tools to get the value of the ``X-Debug-Token``
53+
HTTP header.
54+
55+
The ``profiler`` service also provides the
56+
:method:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler::find` method to
57+
look for tokens based on some criteria::
58+
59+
// gets the latest 10 tokens
60+
$tokens = $profiler->find('', '', 10, '', '', '');
61+
62+
// gets the latest 10 tokens for all URL containing /admin/
63+
$tokens = $profiler->find('', '/admin/', 10, '', '', '');
64+
65+
// gets the latest 10 tokens for local POST requests
66+
$tokens = $profiler->find('127.0.0.1', '', 10, 'POST', '', '');
67+
68+
// gets the latest 10 tokens for requests that happened between 2 and 4 days ago
69+
$tokens = $profiler->find('', '', 10, '', '4 days ago', '2 days ago');
70+
71+
Data Collectors
72+
---------------
73+
74+
The profiler gets its information using some services called "data collectors".
75+
Symfony comes with several collectors that get information about the request,
76+
the logger, the routing, the cache, etc.
77+
78+
Run this command to get the list of collectors actually enabled in your app:
79+
80+
.. code-block:: terminal
81+
82+
$ php bin/console debug:container --tag=data_collector
83+
84+
You can also :doc:`create your own data collector </profiler/data_collector>` to
85+
store any data generated by your app and display it in the debug toolbar and the
86+
profiler web interface.
87+
88+
.. _profiler-timing-execution:
89+
90+
Timing the Execution of the Application
91+
---------------------------------------
92+
93+
If you want to measure the time some tasks take in your application, there's no
94+
need to create a custom data collector. Instead, use the `Stopwatch component`_
95+
which provides utilities to profile code and displayes the results on the
96+
"Performance" panel of the Profiler web interface.
97+
98+
When using :ref:`autowiring <services-autowire>`, type-hint any argument with
99+
the :class:`Symfony\\Component\\Stopwatch\\Stopwatch` class and Symfony will
100+
inject the Stopwatch service. Then, use the ``start()``, ``lapse()`` and
101+
``stop()`` methods to measure time::
102+
103+
// a user signs up and the timer starts...
104+
$stopwatch->start('user-sign-up');
105+
106+
// ...do things to sign up the user...
107+
$stopwatch->lapse('user-sign-up');
108+
109+
// ...the sign up process is finished
110+
$stopwatch->stop('user-sign-up');
111+
112+
.. tip::
113+
114+
Consider using a professional profiler such as `Blackfire`_ to measure and
115+
analyze the execution of your application in detail.
116+
117+
Enabling the Profiler Conditionally
118+
-----------------------------------
119+
120+
.. caution::
121+
122+
The possibility to use a matcher to enable the profiler conditionally was
123+
removed in Symfony 4.0.
124+
125+
Symfony Profiler cannot be enabled/disabled conditionally using matchers, because
126+
that feature was removed in Symfony 4.0. However, you can use the ``enable()``
127+
and ``disable()`` methods of the :class:`Symfony\\Component\\HttpKernel\\Profiler\\Profiler`
128+
class in your controllers to manage the profiler programmatically::
129+
130+
use Symfony\Component\HttpKernel\Profiler\Profiler;
131+
// ...
132+
133+
class DefaultController
134+
{
135+
// ...
136+
137+
public function someMethod(?Profiler $profiler)
138+
{
139+
// $profiler won't be set if your environment doesn't have the profiler (like prod, by default)
140+
if (null !== $profiler) {
141+
// if it exists, disable the profiler for this particular controller action
142+
$profiler->disable();
143+
}
144+
145+
// ...
146+
}
147+
}
148+
149+
In order for the profiler to be injected into your controller you need to
150+
create an alias pointing to the existing ``profiler`` service:
151+
152+
.. configuration-block::
153+
154+
.. code-block:: yaml
155+
156+
# config/services_dev.yaml
157+
services:
158+
Symfony\Component\HttpKernel\Profiler\Profiler: '@profiler'
159+
160+
.. code-block:: xml
161+
162+
<!-- config/services_dev.xml -->
163+
<?xml version="1.0" encoding="UTF-8" ?>
164+
<container xmlns="http://symfony.com/schema/dic/services"
165+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
166+
xsi:schemaLocation="http://symfony.com/schema/dic/services
167+
http://symfony.com/schema/dic/services/services-1.0.xsd">
168+
169+
<services>
170+
<service id="Symfony\Component\HttpKernel\Profiler\Profiler" alias="profiler" />
171+
</services>
172+
</container>
173+
174+
.. code-block:: php
175+
176+
// config/services_dev.php
177+
use Symfony\Component\HttpKernel\Profiler\Profiler;
178+
179+
$container->setAlias(Profiler::class, 'profiler');
180+
181+
Updating the Web Debug Toolbar After AJAX Requests
182+
--------------------------------------------------
183+
184+
`Single-page applications`_ (SPA) are web applications that interact with the
185+
user by dynamically rewriting the current page rather than loading entire new
186+
pages from a server.
187+
188+
By default, the debug toolbar displays the information of the initial page load
189+
and doesn't refresh after each AJAX request. However, you can set the
190+
``Symfony-Debug-Toolbar-Replace`` header to a value of ``1`` in the response to
191+
the AJAX request to force the refresh of the toolbar::
192+
193+
$response->headers->set('Symfony-Debug-Toolbar-Replace', 1);
194+
195+
Ideally this header should only be set during development and not for
196+
production. To do that, create an :doc:`event subscriber </event_dispatcher>`
197+
and listen to the :ref:`kernel.response<component-http-kernel-kernel-response>`
198+
event::
199+
200+
use Symfony\Component\HttpKernel\Event\FilterResponseEvent;
201+
202+
// ...
203+
204+
public function onKernelResponse(FilterResponseEvent $event)
205+
{
206+
if (!$this->getKernel()->isDebug()) {
207+
return;
208+
}
209+
210+
$response = $event->getResponse();
211+
$response->headers->set('Symfony-Debug-Toolbar-Replace', 1);
212+
}
213+
20214
.. toctree::
21-
:maxdepth: 1
215+
:hidden:
22216

23217
profiler/data_collector
24-
profiler/profiling_data
25-
profiler/matchers
26-
profiler/wdt_follow_ajax
218+
219+
.. _`Single-page applications`: https://en.wikipedia.org/wiki/Single-page_application
220+
.. _`Stopwatch component`: https://symfony.com/components/Stopwatch
221+
.. _`Blackfire`: https://blackfire.io/

‎profiler/matchers.rst

Lines changed: 0 additions & 66 deletions
This file was deleted.

‎profiler/profiling_data.rst

Lines changed: 0 additions & 46 deletions
This file was deleted.

0 commit comments

Comments
 (0)
0