WebStorm 9.0.2 Web Help

Tracing with Spy-js

Spy-js is a tool for JavaScript developers that allows to simply debug/trace/profile JavaScript running on different platforms/browsers/devices. The tool fills gaps that existing browser development tools have and tackles common development tasks from a different angle.

The tool also traces NodeJS applications.

On this page:

Preparing for Tracing with Spy-js

  1. Download and install NodeJS because it is used by the Spy-js trace server.
  2. Make sure the Spy-js plugin is enabled. The plugin is bundled with WebStorm and activated by default. If it is not, enable it as described in Enabling and Disabling Plugins.

Spy-js Basics

With Spy-js, you can trace both Web applications and NodeJS applications. Although the Spy-js UI in either case is the same, the mechanisms of the tracing differ.

In order to trace a script, Spy-js has to modify it on the fly. The modification does not affect the logic of the script, it is just inserting instrumentation instructions that report back to Spy-js UI about what functions have been invoked when the script executes.

  • To modify website scripts, Spy-js has to act as a proxy server that "sits" between your browser and the website you are tracing. When you open a traced website in your browser, Spy-js receives the script request, requests the script from your website, receives the script, makes the required modifications, and sends it back to your browser where the script executes, and sends the runtime information to the Spy-js UI.

    The proxy server can be configured automatically by selecting the Automatically configure system proxy check box in the Run/Debug Configuration: Spy-Js dialog or manually. See how to configure proxy settings manually on Windows, Mac, Ubuntu, iOS, Android, Windows Phone. Please note that some desktop browsers have their own screens for proxy settings configuration.

  • In case of a NodeJS application, Spy-js cannot get between the NodeJS server and the scripts if the application is already running. Therefore to trace a NodeJS application, spy-js launches the NodeJS server and the application itself. This enables Spy-js to intercept and modify script requests and scripts, whereupon the tracing procedure runs as when tracing a website script.

A Spy-js session is initiated from WebStorm through a run configuration, see Initiating a Spy-js Session.

Spy-js UI

All the tracing-related activities, such as viewing captured events, examining their call stacks, navigating to the source code, etc. are performed in the dedicated Spy-Js Tool Window, in particular in its Trace Run Tab. The tab consists of a toolbar and three panes:

  • 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, WebStorm 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 colour indicators to help distinguishing between them when working with the Event Stack pane. By hovering your mouse over a script file name, 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.

  • 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 file name 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 the script selected in the Events pane or the script whose function is double clicked in the Event Stack pane. A trace file is named <file name>.js.trace. When you double click an item in the stack tree or select it and choose Jump to Trace on 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 on the context menu.

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

    • 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 on the context menu of the selection. If the traced site is mapped with a WebStorm project, WebStorm 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 WebStorm project, WebStorm 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 WebStorm project, WebStorm opens the source file on any attempt to edit the opened trace file.

  • 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.

Spy-js Tracing Session

Initiating a Spy-js Tracing Session

The way you initiate a tracing session depends on the type of the application you are going to trace.

Launching a tracing session of a Web application

  1. Create a run configuration of the type Spy-js. To do that, choose Run | Edit Configurations on the main menu, click the Add New Configuration toolbar button add.png, and choose Spy-js on the context menu. In the Run/Debug Configuration: Spy-js dialog box that opens, specify the following:
    1. The location of the Node interpreter.
    2. The trace server port. This port number must be the same as your system proxy port. If the Automatically configure system proxy check box is selected, the specified port number is automatically set for the system proxy server. Otherwise you will have to specify the value of the field in the system proxy settings manually.

      The trace server port is filled in automatically. To avoid port conflicts, it is recommended that you accept the suggested value and keep the Automatically configure system proxy check box selected.

    3. The way to configure the proxy server.

      To have the system proxy server activated automatically with the port specified in the Trace server port field, select the Automatically configure system proxy check box.

      Clear the Automatically configure system proxy check box to specify proxy settings manually. See how to configure proxy settings manually on Windows, Mac, Ubuntu, iOS, Android, Windows Phone. Please note that some desktop browsers have their own screens for proxy settings configuration.

    4. From the Use dropdown list, choose the way to specify the way to configure a tracing session.
      • To have Spy-js apply its internal predefined configuration, choose Default configuration.
      • To have your custom manually created configuration applied, choose the Configuration file option and then specify the location of your custom configuration file in the Configuration field below.

        A configuration file is a JavaScript file with the extension .js or .conf.js that contains valid JavaScript code that meets the Spy-js configuration requirements. If WebStorm detects files with the extension .conf.js in the project, these files are displayed in the drop-down list.

        Type the path to the configuration file manually or click the Browse button browseButton and choose the location in the dialog box that opens. Once specified, a configuration file is added to the drop-down list so you can get if next time from the list instead of specifying the path.

  2. To launch a tracing session, click the Run toolbar button run. The Spy-Js Tool Window opens with an empty Trace Run tab and a Trace Proxy Server tab informing you about the status of the proxy server.
  3. Switch to the browser and refresh the page to start debugging from. Spy-js starts capturing events on this page and the Spy-js tool window shows them in the Events pane.

Launching a tracing session of a NodeJS application

  1. Create a run configuration of the type Spy-js for NodeJS. To do that, choose Run | Edit Configurations on the main menu, click the Add New Configuration toolbar button add.png, and choose Spy-js for NodeJS on the context menu. In the Run/Debug Configuration: Spy-js for NodeJS dialog box that opens, specify the following:
    1. The location of the Node interpreter.
    2. The Node parameters, that is, the NodeJS-specific command line options to be passed to the NodeJS executable file. For example, to enable tracing ECMAScript 6 scripts, specify --harmony as a Node parameter. Note that Node.js must be version 0.11.13 or higher.
    3. The working directory of the application. All references in the starting NodeJS application file, for example, includes, will be resolved relative to this folder, unless such references use full paths.

      By default, the field shows the project root folder. To change this predefined setting, choose the desired folder from the drop-down list, or type the path manually, or click the Browse button browseButton.png and select the location in the dialog box, that opens.

    4. The JavaScript file to start the application with.

      If you are going to trace CoffeeScript, specify the path to the generated JavaScript file. The file can be generated externally or through transpilation using file watchers. For more details, see Transpiling CoffeeScript to JavaScript.

    5. The application parameters: the NodeJS-specific arguments to be passed to the starting NodeJS application file through the process.argv array.
    6. The environment variables for the NodeJS executable file, if applicable. See Run/Debug Configuration: Spy-Js for Node.js for details.
    7. The configuration file with the configuration settings to apply to the tracing session.

      A configuration file is a JavaScript file with the extension .js or .conf.js that contains valid JavaScript code that meets the Spy-js configuration requirements. If WebStorm detects files with the extension .conf.js in the project, these files are displayed in the drop-down list.

      Type the path to the configuration file manually or click the Browse button browseButton and choose the location in the dialog box that opens. Once specified, a configuration file is added to the drop-down list so you can get if next time from the list instead of specifying the path.

    8. The trace server port. This port number must be the same as your system proxy port. If the Automatically configure system proxy check box is selected, the specified port number is automatically set for the system proxy server. Otherwise you will have to specify the value of the field in the system proxy settings manually.

      The trace server port is filled in automatically. To avoid port conflicts, it is recommended that you accept the suggested value and keep the Automatically configure system proxy check box selected.

  2. To launch a tracing session, click the Run toolbar button run. The Spy-js tool and the NodeJS application start. The Spy-Js Tool Window opens showing the captured events in the Trace Run tab.

Saving and Loading Tracing Sessions

You can save an image of a tracing session and load this image at any time later. The .json files that store the calls and properties of the session are compressed into a zip archive. Upon request, when you choose Load trace, the .json files are extracted from the archive and loaded into Spy-js.

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.

To save an image of a tracing session

  • Click the cogwheel_blue button on the Events toolbar, and then choose Save trace from the list. WebStorm compresses all the affected .json files in a zip archive and opens the folder where the archive is saved.

To load an image of a previous tracing session

  1. Initiate a tracing session of the same type as the session you are going to load the image of: a Spy-js or a Spy-js for NodeJS respectively, see Initiating a Spy-js Tracing Session above. We need to have this fake session running because otherwise Spy-js would be inactive and thus the load trace functionality would be unavailable.

    Of course you can load a trace while actually tracing an application, but in this case the currently running session will be lost after loading.

  2. When the session starts, click the cogwheel_blue button on the Events toolbar and choose Load Trace from the list.
  3. In the dialog box that opens, choose the location of the zip archive with the image of the desired session. Spy-js stops the running and shows the loaded trace in a new tab named Loaded <loaded session>.

    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.

Configuring the Range of Events to Display

By default, the Spy-js tool captures all events on all opened Web pages, excluding https secure web sites, unless you have specified a URL address explicitly in the run configuration. The Events pane of the Spy-js tool window shows all captured events. If for some reasons you do not want to have all events captured, you can suppress capturing some of them by applying user-defined event filters. All the available filters are listed upon clicking the Capture Events button iconFilter on the toolbar, the currently applied filter is marked with a tick. By default the Capture All predefined filter is applied. You can define new custom filters or add event patterns to existing filters on the fly.

Defining a new event filter

  1. Click the Capture Events button iconFilter on the toolbar, and then choose Edit Capture Exclusions from the list.
  2. In the Spy-Js Capture Exclusions Dialog that opens, click the Add toolbar button add in 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 add, the Add Condition to Exclusion dialog box opens. Type a pattern in the Value/pattern text box, in theCondition type drop-down 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, WebStorm brings you to the Spy-Js Capture Exclusions Dialog.

    To edit a rule, select it in the list, click edit1, and update the rule in the dialog box that opens. To remove a rule, select it in the list and click delete.

Creating exclusion rules on the fly

  • To add an event to an exclusion filter on the fly, select the event to exclude and choose Mute <event name> event or Mute <script name> file.

Synchronization and Navigation between the Panes and the Editor

The Events and Event Stack panes are synchronized: when you click an event or script in the Events pane, its call stack is displayed in the Event Stack pane. To have also the corresponding trace file opened in the editor, press the Autoscroll to Trace toggle button on the toolbar.

The Event Stack pane is synchronized with the editor: when you click an item in the stack tree twice, the corresponding trace file opens in the editor with the cursor positioned at the clicked function.

To synchronize the Events pane directly with the editor, press the Autoscroll to Trace toggle button on the toolbar. In this case, as soon as you click a node in the Events pane, its call stack is displayed in the Event Stack pane and the corresponding trace file is opened in the editor. With the Autoscroll to Trace mode turned on, when you navigate through the Event Stack the corresponding files are also automatically opened in the editor with the corresponding functions highlighted.

Navigating from an event or a script to the trace file

  • Activate automatic navigation:
    1. In the Events pane, press the Autoscroll to Trace toggle button on the toolbar.
    2. Click the required event or script.
  • In the Event Stack pane, click the required item in the call stack twice or choose Jump to Trace. on the context menu. The trace file opens with the cursor positioned at the clicked function.

Navigating from an event or script to the source file

  • In the Event Stack pane, select the required item in the call stack and choose Jump to Source on the context menu of the selection.

Navigating from a function to its call

  • In the Event Stack pane, select the required item in the call stack and choose Jump to Caller on the context menu of the selection.

Expanding the Basic Completion List with Runtime Data (Spy-js Autocompletion)

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 position the caret at a symbol in the source file and press Ctrl+Space, Spy-js retrieves data from the browser or from the running NodeJS application and merges it with the basic completion list according to the following rules:

  1. 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.
  2. Objects retrieved by Spy.js are shown on top of the list and marked with the icon_spy_js.png icon. If a retrieved object is specific for a browser, the object is marked with the icon_spy_js.png icon and with the icon of this browser.

Activating spy-js autocompletion

  • Click the cogwheel_blue button on the Events toolbar, and then choose Enable Spy-js autocomplete and magnifier from the list.

Evaluating Expressions without Running a Debugging Session (Spy-js Magnification)

The term Spy-js magnification denotes evaluating expressions without actually running a debugging session. When you click the expression in question or position the caret at it and press Ctrl+Alt+F8, a tooltip is displayed below the expression showing the expression value. If Spy-js retrieves several values, click 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.

By default, the functionality is turned off.

Activating spy-js magnification

  • Click the cogwheel_blue button on the Events toolbar, and then choose Enable Spy-js autocomplete and magnifier from the list.

See Also

Last modified: 11 December 2014
comments powered by Disqus