1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
=================
JavaScript Tracer
=================
How to use the JavaScript Tracer
*****************************************
.. note::
This feature is still under development and may drastically change at any time.
You will have to toggle `devtools.debugger.features.javascript-tracing preference` preference to true in about:config
before opening DevTools in order to use it.
Once enabled, you have three ways to toggle the tracer:
* From the debugger, via the tracer icon on the top right of its toolbar |image1|.
You can right click on this button (only when the tracer is OFF) to configure its behavior.
* From the console, via the `:trace` command.
You can execute `:trace --help` to see all supported optional arguments.
Otherwise `:trace` will either start or stop the JS Tracer based on its current state.
* From the page, via Ctrl+Shift+5 key shortcut (or Cmd+Shift+5 on MacOS).
Triggering this key shortcut will either start or stop the JS Tracer based on its current state.
This will use the configuration current defined in the Debugger tracer icon's context menu.
.. |image1| image:: trace-icon.svg
Tracer options
**************
Logging output
--------------
* Web Console (Default)
The JS Tracer will log all JS function calls into the Web Console panel.
This helps see the precise order of JS calls versus anything logged in the console:
console API usages, exceptions, CSS warnings, ...
|image2|
(`:trace --logMethod console`)
* Debugger Sidebar
The JS Tracer will log all JS function calls into the Debugger panel, in the Tracer sidebar.
This involves a user interface dedicated to navigate through all the traces.
You can easily see all the DOM Events triggering JavaScript code, and browser all the stacks displayed
as a tree.
This UI is an under-development prototype and may change significantly or even be dropped in the future.
|image5|
(`:trace --logMethod debugger-sidebar`)
* Profiler record
The JS Tracer will log all JS function calls in the background. When you stop tracing,
the traces will be shown in a new tab loading the `Firefox Profiler <https://profiler.firefox.com>`_ UI.
From there, you can see the traces via the Stack Chart panel,
and also upload the traces in order to share it with someone.
|image4|
(`:trace --logMethod profiler`)
* Stdout
The JS Tracer will log all JS function calls in your terminal (assuming you launched Firefox from a terminal).
This output is especially useful when the page involves lots of JS activity as it is faster to render.
You may also use various terminal tricks to filter the output the way you want.
Note that source URLs are flagged with some special characters so that most terminal will allow you to click on them.
If Firefox is your default browser, the links should open the debugger on the right location.
Assuming this is the same Firefox instance that is logging the traces and the same instance that the terminal app tries to open.
And you need DevTools to be kept opened, otherwise the link will open as a regular URL in a new tab.
.. code-block:: bash
—DOM | click
—[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:37892 - λ add/v.handle
——[baseline]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:39398 - λ dispatch
———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40960 - λ fix
————[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:41576 - λ ce.Event
———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:30171 - λ get
————[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:29696 - λ F
———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40177 - λ handlers
(`:trace --logMethod stdout`)
.. |image2| image:: console-trace.png
:class: border
:alt: The JS Traces displayed in the Web Console
.. |image4| image:: profiler-trace.png
:class: border
:alt: The JS Traces displayed in the Firefox Profiler UI
.. |image5| image:: debugger-sidebar.png
:class: border
:alt: The JS Traces displayed in the Debugger sidebar
Delayed start
-------------
There is two ways to delay the actual start of the JS Tracer.
Both require to request the tracer to start by clicking on the debugger tracer icon, or run the `:trace` console command, or trigger the key shortcut.
The Tracer will then be in pending mode, which is indicated via a blue badge on the tracer icon. |image3|
* on next user interaction
The tracer will only really start logging function calls when the first clicking or pressing a key on the page.
To be precise, the tracer will start on first mousdown or keydown event.
(`:trace --on-next-interaction`)
* on next page load
The tracer will only really start when navigating to another page or reloading the current page.
It will start just before anything starts being executed.
It help see the very first JavaScript code running on the page.
(Note that this feature is not available via the console command.)
.. |image3| image:: pending-icon.png
:class: border
Tracing function returns
------------------------
You may optionally log function returns, i.e. the precise execution ordering when a function ends and returns.
This is disabled by default as it doubles the output of the tracer.
Note that this option is enabled by default for the profiler output, without any major performance hit,
in order to properly record each function call duration.
.. image:: trace-returns.png
(`:trace --returns`)
Tracing values
--------------
You may optionally display all function call arguments as well as function return values (if enabled).
This is disabled by default as it complexify the output of the tracer, making it slower and less readable.
Note that the profiler output doesn't support this feature.
.. image:: trace-returns-with-values.png
.. image:: trace-values.png
(`:trace --values`)
Web Console Command only options
--------------------------------
* Log DOM Mutations
You may optionally trace all DOM Mutations happening on the page.
The mutation will appear according to their precise execution order versus JavaScript code modifying the DOM (JS Traces),
but also errors, warnings and console API logs.
By default, the console command argument `--dom-mutations` will record all types of mutations: new nodes being added to the document,
attributes changed on a node and node being removed from the document.
The argument also accept a coma separated list of options to control which type of mutation should be logged.
(`:trace --dom-mutations` === `:trace --dom-mutations add,attributes,remove`)
* Depth limit
You may optionally limit the depth of function calls being logged.
For example, limiting the depth to "1" will typically only log the event listener function. i.e. the top level function being called by the Web Engine.
This allows to drastically reduce the output of the trace, but may hide precious information.
The tracer will not be automatically stopped by this option. This will only ignore nested function calls passed the given depth limit.
For example, while :trace without any argument would log the following on bugzilla:
.. code-block:: bash
—DOM | mousedown
—[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:37892 - λ add/v.handle
——[baseline]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:39398 - λ dispatch
———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40960 - λ fix
————[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:41576 - λ ce.Event
———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:30171 - λ get
————[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:29696 - λ F
———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40177 - λ handlers
—DOM | mouseup
—[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:37892 - λ add/v.handle
——[baseline]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:39398 - λ dispatch
———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40960 - λ fix
————[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:41576 - λ ce.Event
———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:30171 - λ get
————[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:29696 - λ F
———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40177 - λ handlers
running `:trace --max-depth 1` will give us:
.. code-block:: bash
—DOM | mousedown
—[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:37892 - λ add/v.handle
—DOM | mouseup
—[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:37892 - λ add/
and running `:trace --max-depth 3` will give us:
.. code-block:: bash
—DOM | mousedown
—[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:37892 - λ add/v.handle
——[baseline]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:39398 - λ dispatch
———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40960 - λ fix
———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:30171 - λ get
———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40177 - λ handlers
—DOM | mouseup
—[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:37892 - λ add/v.handle
——[baseline]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:39398 - λ dispatch
———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40960 - λ fix
———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:30171 - λ get
———[interpreter]—> https://bugzilla.mozilla.org/static/v20240305.1/js/jquery/jquery-min.js:2:40177 - λ handlers
(`:trace --max-depth 5`)
* Record limit
You may optionally limit the number of "records" being logged, after which the tracer will be automatically stopped.
A record is composed of one top level function call, including all its nested function being called from this top level one.
This option can be especially useful in combination to tracer on next user interaction.
This can help narrow down to a very precise code acting only on a mouse or key event processing.
(`:trace --max-records 10`)
|
