Trace run tab
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 |
|---|---|---|
| Expand all Ctrl+NumPad + | Click this button to have all the nodes in the list expanded. |
| Collapse all Ctrl+NumPad - | Click this button to have all the nodes in the list collapsed. |
| Up the Stack Trace | Click this button to navigate to the previous traced page in the stack trace. |
| Down the Stack Trace | Click this button to navigate to the next traced page in the stack trace. |
| Navigate with Single Click | Press this toggle button to have the list in the Events pane automatically synchronized with the Editor.
|
| 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 To define a custom event filter:
To activate a filter, select the checkbox next to the required filter in the list. |
| 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:
| |
to stop the tracing session externally by means of the standard 
indicating that subsequent click will lead to force termination of the application, for example on Unix 
icon. If a retrieved object is specific to a browser, the object is marked with the 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 the mouse 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 to help distinguishing 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.
|
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.
|
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
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
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
Click the Capture Events button
on the toolbar, and then choose Edit Capture Exclusions from the list. In the Spy-js Capture Exclusions Dialog that opens, click Add
on the left-hand pane. 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
, 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
, and update the rule in the dialog that opens. To remove a rule, select it in the list and click 
.
To choose a filter to apply
Click
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 cursor positioned 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):
|
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, see 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. |
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 of Function 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. |