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