PhpStorm
 
2023.2
Shortcuts: Windows
Get PhpStorm
You are viewing the documentation for an earlier version of PhpStorm.
  1. Reference
  2. Tool Windows Reference
  3. Spy-js tool window
  4. Trace run tab

Trace run tab

Last modified: 07 September 2023

The tab consists of a toolbar and three panes: Events Pane, Event Stack Pane, and Quick Evaluation Pane.

Events toolbar

Use the buttons on the toolbar to control the range of events to capture, configure their presentation, and navigate through the list of captured events.

Item

Tooltip and shortcut

Description

The Expand All button

Expand all CtrlNumPad +

Click this button to have all the nodes in the list expanded.

the Collapse All button

Collapse all CtrlNumPad -

Click this button to have all the nodes in the list collapsed.

Previous

Up the Stack Trace

Click this button to navigate to the previous traced page in the stack trace.

Next

Down the Stack Trace

Click this button to navigate to the next traced page in the stack trace.

Navigate with Single Click

Navigate with Single Click

Press this toggle button to have the list in the Events pane automatically synchronized with the Editor.

  • When the button is pressed: as soon as you click an event in the Events pane, the details of the event are displayed in the Event Stack pane and the script that is invoked by the event is opened in the editor automatically.

    When you navigate through the Event Stack with the Autoscroll to Trace mode turned on, the corresponding files are also automatically opened in the editor with the calling functions highlighted.

  • When the button is released: the script that is invoked by the event is opened in the editor only upon double-clicking the event in the Event Stack pane.

Capture Events

Capture Events

Click this button to configure the range of events to be captured and shown in the Events list.

By default, Spy-js captures all events on all opened Web pages, excluding https secure web sites, unless you specify their URL addresses explicitly in the run configuration. All the captured events are shown on the Events pane of the Spy-js tool window. You can suppress capturing some types of events by applying user-defined event filters. When you click Filters, the list shows all the available filters, the currently applied filter is marked with a tick. By default the Capture All predefined filter is applied. To stop capturing events without stopping the application, choose Mute All. For more information, refer to Configuring the event capturing policy.

To define a custom event filter:

  1. Click Capture Events, and then choose Edit Capture Exclusions from the list.

  2. In the Spy-js Capture Exclusions Dialog that opens, click Add App general add on the left-hand pane.

  3. In the right-hand pane, specify the filter name in the Exclusion name field and configure a list of exclusion rules.

    • To add a rule, click App general add, the Add Condition to Exclusion dialog opens. Type a pattern in the Value/pattern field, in the Condition type list specify whether the pattern should be applied to event types or script names. Note that glob pattern matching is used. When you click OK, PhpStorm brings you to the Spy-js Capture Exclusions Dialog.

    • To edit a rule, select it in the list, click App actions edit, and update the rule in the dialog that opens. To remove a rule, select it in the list and click App general remove.

To activate a filter, select the checkbox next to the required filter in the list.

Settings

Click this button to remove all or some events from tracing and have the corresponding trace files closed in the editor. Choose one of the following options on the list that is displayed:

  • Remove all: choose this option to cancel tracing of all captured events without closing the trace files in the editor.

  • Close all trace files: choose this option to have all trace files in the editor closed but keep tracing the corresponding event. To remove an event or script from tracing and close the corresponding trace files in the editor, choose Remove from the context menu of the event or script.

  • Remove all inactive: choose this option to remove all nodes for pages that are not active anymore (for example, because the pages have been closed in browser).

  • Save trace: choose this option to save an image of the current session. Spy-js stores the calls and properties of a tracing session in .json files that can be compressed into a zip archive. You can extract them at any time later to load the tracing session image into Spy-js.

  • Load trace: choose this option to have a previously saved image of a tracing session loaded into Spy-js. The .json files that store the calls and properties of that session are extracted and imported.

    Note that a loaded image does not restore the session because no scripts are actually executed. All you can do is analyze the flow and properties of previously executed code.

  • Close all trace files on session stop: choose this option to have all trace files in the editor closed when you click the Stop button Stop to stop the tracing session externally by means of the standard shutdown script.

    Clicking the button once invokes soft kill allowing the application to catch the SIGINT event and perform graceful termination (on Windows, the Ctrl+C event is emulated). After the button is clicked once, it is replaced with the Kill Process button indicating that subsequent click will lead to force termination of the application, for example on Unix SIGKILL is sent.

  • Enable Spy-js autocomplete and magnifier: choose this option to have the basic completion list expanded with runtime data (Spy-js auto-completion) and to get the possibility to evaluate expressions without actually running a debugging session (Spy-js magnification). By default, the functionality is turned off.

    The term Spy-js autocompletion denotes expanding the basic completion list with suggestions retrieved from the runtime data. The Spy-js autocompletion functionality is available from source files for the code that has already been executed (highlighted green in the corresponding trace file).

    When you place the caret at a symbol in the source file and press CtrlSpace, Spy-js retrieves data from the browser or from the running Node.js application and merges it with the basic completion list according to the following rules:

    If an object both is present on the basic completion list and is retrieved from the runtime, the variant that provides more information about parameters, attributes, their type, etc. remains on the list.

    The term Spy-js magnification denotes evaluating expressions without actually running a debugging session. When you click an expression or place the caret at it and press CtrlAltF8, a tooltip is displayed below the expression showing the expression value. If Spy-js retrieves several values, click App general add icon in the tooltip to expand the list of values.

    The magnification functionality is available from source files for both executed and not yet executed code.

  • Spy-js supports source maps, which means that you can now jump from the Event Stack pane right to the original source code in ECMAScript 6, TypeScript or CoffeeScript and observe what code fragments were executed. Use the following options to configure the way source maps are treated:

    • Enable source map look-up: choose this option to enable navigation to the ECMAScript 6, TypeScript or CoffeeScript source code using the source maps generated during compilation.

    • Enable source map generation: choose this option to generate source maps for everything to map the instrumented code. Choose this option if you are going to debug the original code in Chrome Dev Tools or FireFox FireBug development tools.

    • Always open source mapped trace if available: choose this option to have Spy-js try to open the mapped trace file when you invoke navigation from an event to its caller.

Events pane

The pane shows a tree of captured events. The top-level nodes represent documents that are Web pages involved in tracing. When you hover over a document, PhpStorm displays a tooltip with the URL address of the document, the browser in which it is opened, and the operating system the browser is running on. The document node is also supplied with an icon that indicates the browser in which it is opened.

Under each document node, events detected on the page and scripts started from it are listed. Events of the same type are grouped into visual containers. The header of a container displays the name of the events grouped in it, the average execution time across all the events within the container, and the number of events inside the container. You can expand each node and inspect the individual events in it.

Script file names have different color indicators that help to distinguish between them when working with the Event Stack pane. By hovering your mouse over a script filename, you can see the full script URL.

Once an event is clicked, its call stack is displayed in the Event Stack pane. The stack is represented by a tree of function calls.

Context menu of a Document node

Menu item

Description

Remove

Choose this option to cancel tracing all the scripts on the selected page and remove the selected node with all the items under it from the Events pane. All the currently opened trace files remain opened in the editor.

Remove all children

Choose this option to delete the items under the selected page but keep tracing it so that new events from the page are still received. The document node itself remains in the Event pane, and all the currently opened trace files remain opened in the editor.

Remove and close trace file(s)

Choose this option to cancel tracing all the scripts on the selected page, remove the selected node and all the items under it from the Events pane, and close the corresponding trace files in the editor.

Close trace file(s)

Choose this option to close all the currently opened trace files that correspond to the selected document node and items under it. The document node and the items under it remain in the Events pane.

Refresh the page in browser

Choose this option to reload the page that corresponds to the selected document node. Tracing of the selected node is abandoned, a new document node for tracing the same page is created, and the old node becomes inactive.

Try closing the page in browser

Choose this option to close the page that corresponds to the selected node. Tracing of the selected node is abandoned, and the node becomes inactive.

Show application dependency diagram

Choose this option to build a diagram with the dependencies within the entire application.

  • The diagram is opened in a separate editor tab. The nodes in the diagram represent your project files, while the edges represent the fact that there’s one or more functions in the source file that invoke functions in the target file.

  • To examine the details of a node or an edge, select the node or the edge and view its Details tree in a dedicated pane in the upper right-hand corner of the editor. The pane displays the connecting function combinations, along with event(s) the calls are made within and the number of calls made.

Context menu of an event or script

Menu item

Description

Mute event

Choose this option to add an event to an exclusion filter on the fly.

Mute script

Choose this option to add a script to an exclusion filter on the fly.

Remove

Choose this option to cancel tracing the selected event or script, remove the selected item from the Events pane, but leave the corresponding trace files opened in the editor.

Add label

Choose this option to set a timestamp label. Timestamp labels help you to analyze your code execution within a specific period of time. For example, you can set two timestamp labels and view which events were captured between them. Or on the contrary, you can locate the events that were not captured within a certain period of time although you expected them to be and thus detect performance problems.

Show event dependency diagram

Choose this option to build a diagram with the dependencies in which the event selected event is involed.

  • The diagram is opened in a separate editor tab. The nodes in the diagram represent your project files, while the edges represent the fact that there’s one or more functions in the source file that invoke functions in the target file.

  • To examine the details of a node or an edge, select the node or the edge and view its Details tree in a dedicated pane in the upper right-hand corner of the editor. The pane displays the connecting function combinations, along with event(s) the calls are made within and the number of calls made.

Configuring the range of events to capture

By default, Spy-js captures all events on all opened Web pages, excluding https secure web sites, unless you specify their URL addresses explicitly in the run configuration. All the captured events are shown on the Events pane of the Spy-js tool window. You can suppress capturing some types of events by applying user-defined event filters.

You can define new custom filters or add event patterns to existing filters on the fly.

To view the available configured filters

  • Click the Capture Events button Capture Events on the toolbar. the currently applied filter is marked with a tick. By default the Capture All predefined filter is applied.

To stop capturing events without stopping the application

  • Click the Capture Events button Capture Events on the toolbar and choose Mute All from the context menu. The application is still running but the Events pane shows the last captured event. This is helpful if you want to analyze a script and therefore need it to be displayed in the Events pane but not removed as new events are captured.

To define a new event filter

  1. Click the Capture Events button Capture Events on the toolbar, and then choose Edit Capture Exclusions from the list.

  2. In the Spy-js Capture Exclusions Dialog that opens, click Add App general add on the left-hand pane.

  3. In the right-hand pane, specify the filter name in the Exclusion name field and configure a list of exclusion rules.

    • To add a rule, click App general add, the Add Condition to Exclusion dialog opens. Type a pattern in the Value/pattern field, in the Condition type list specify whether the pattern should be applied to event types or script names. Note that glob pattern matching is used. When you click OK, PhpStorm brings you to the Spy-js Capture Exclusions Dialog.

    • To edit a rule, select it in the list, click App actions edit, and update the rule in the dialog that opens. To remove a rule, select it in the list and click App general remove.

To choose a filter to apply

  • Click Filter and select the checkbox next to the required filter in the list. If no filters are configured or none of the available filters fits the task, create a new filter as described above.

While navigating through the tree of already captured events in the Events pane, you may come across some events or scripts that you definitely do not want to trace. You can create a filter as described above but in this case you will have to leave the pane. With PhpStorm, you can create an exclusion rule based on any event or script, as soon as you have detected such event or script, right from the Events pane.

To create an exclusion rule on the fly

  • Select the event to exclude and choose Mute <event name> event or Mute <script name> file. If a user-defined filter is currently applied, the new rule is added to it silently. If Capture All is currently active, the Spy-js Capture Exclusions Dialog opens, where you can create a new filter based on the selected event or script or choose an existing filter and add the new rule to it.

Event Stack pane

Once an event in the Events pane is clicked, its call stack is displayed in the Event Stack pane. The stack is represented by a tree of function calls. Each tree node represents the invoked function. Node text contains the total execution time, the script filename and the function name. When you click a node, the Quick Evaluation pane shows additional function call details, parameter values and return value, occurred exception details if there was one during the function execution.

The pane is synchronized with the editor, so you can navigate from an item in the stack tree to the corresponding trace file or source file.

  • A trace file is a write-protected prettified version of a script and is named <script name>.js.trace. When you double-click an item in the stack tree or select it and choose Jump to Trace from the context menu of the selection, the corresponding trace file opens in the editor with the caret placed at the clicked function. Another approach is to press the Autoscroll to Trace toggle button and select various stack nodes. In this case, the trace file opens when you click an event or script in the Events pane.

    You can not only jump to a function but also to the place in the code where it was called from. To do that, select the required item and choose Jump to Caller from the context menu.

    The contents of the file are highlighted to display the code execution path of the selected stack node.

  • When you are tracing an application with ECMASript6, CoffeeScript, and TypeScript code, Spy-js also generates mapped trace files. These are EcmaScript 6, TypeScript, or CoffeeScript trace files with the extensions .ts.trace, .coffee.trace, or .js.trace. The fragments of code in these files are highlighted as if they were really executed.

  • You can also navigate to the source file displayed as is, without prettifying, by selecting an item in the Event Stack pane and choosing Jump to Source from the context menu of the selection. If the traced site is mapped with a PhpStorm project, PhpStorm detects the corresponding local file according to the mapping and opens this file in the editor. If you are tracing a site that is not mapped to a PhpStorm project, PhpStorm opens the read-only page source, just as if you chose View Page Source in the browser.

    When the traced site is mapped with a PhpStorm project, PhpStorm opens the source file on any attempt to edit the opened trace file.

Context menu of a script or function

Item

Description

Jump to Caller

Choose this option to navigate to the fragment in the trace file from where the currently selected item was called. When you are tracing an application with ECMASript6, CoffeeScript, and TypeScript code, PhpStorm opens either the trace JavaScript file or the mapped trace file (TypeScript, CoffeeScript, or ECMAScript6):

  • If the Always open source mapped trace if available option is selected, the corresponding mapped trace file opens.

  • If the Always open source mapped trace if available option is not selected, the JavaScript trace file opens.

Jump to Trace

Choose this option to navigate to the definition of the currently selected item in the trace file.

Jump to Source

Choose this option to navigate to the definition of the currently selected item in the source file.

Mute this File

Choose this option to add the selected script to an exclusion filter on the fly, refer to Configuring the Range of Events to Capture.

Capture only this file

Search this function calls across all events

Choose this option to navigate between the calls of a function within the whole trace (across all the traced events) as described in Advanced trace search.

Navigate to

Use the options under this item to move through the whole stack based on calls and locate the functions that have not been called, that is, locate the fragments of code that have not been executed and analyze the reason for them to be skipped.

The following six actions are available: move to the next/previous call of the next/current/previous function in a trace file. The full list of actions is available from the context menu in the Event Stack pane. Moving to the next and previous calls of the selected function, to the previous call of the previous function, and to the next call of the next function are also available from the navigation toolbar of the Event Stack pane.

spy_js_advanced_navigation_1.png
When you choose one of these actions, the caret jumps to the call in the stack. If the Autoscroll to Trace toggle button is pressed, the corresponding trace file opens automatically with the caret placed at the call.

Synchronization between the panes and the editor

The Event Stack pane is synchronized with the Events pane and with the editor.

To view the call stack of a script or an event

  • Click the event or the script in the Events pane. Its call stack is shown in the Event Stack pane.

  • Optionally: to open the corresponding trace file in the editor automatically, press the Autoscroll to Trace toggle button on the toolbar.

To open the trace file of an event or a script in the editor

A trace file is a write-protected prettified version of a script and is named <script name>.js.trace.

  • In the Event Stack pane, click the script or event twice or choose Jump to Trace on its context menu.

  • Activate automatic navigation (click Autoscroll to Trace) and click the required event or script in the Events pane.

To synchronize the Events pane directly with the editor

  • Press the Autoscroll to Trace toggle button on the toolbar.

    After that, on clicking a node in the Events pane, PhpStorm shows its call stack in the Event Stack pane aqnd opens the corresponding trace file in the editor. Also, when you scroll through the Event Stack PhpStorm automatically opens the corresponding files in the editor and highlights the called functions.

Quick Evaluation pane

When you click a node in the Event Stack pane, the Quick Evaluation pane shows additional function call details, parameter values and return value, occurred exception details if there was one during the function execution.

Context menu offFunction call details

The context menu is available from all items displayed in the pane.

Item

Description

Inspect

Choose this option to open the Inspect dialog.

Copy Value

Choose this option to copy the value of the selected node to the clipboard.

Compare Value with Clipboard

Choose this option to open the Differences viewer for files which displays the value of the selected node and the value in the clipboard so you can compare them.

Copy Name

Choose this option to copy the name of the selected node to the clipboard.

See also

Reference

Language and Framework-Specific Guidelines

External Links