JetBrains Rider 2018.1 Help

Spy-js

Spy-js is a tool for JavaScript developers that lets you 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 Node.js, server-side, applications.

Preparing for tracing with Spy-js

  1. Download and install Node.js because it is used by the Spy-js trace server.
  2. Make sure the Spy-js repository plugin is installed and enabled. The plugin is not bundled with JetBrains Rider, but it can be installed from the JetBrains plugin repository as described in Installing, Updating and Uninstalling Repository Plugins and Enabling and Disabling Plugins.

Spy-js basics

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

  • 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 checkbox 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 Node.js application, Spy-js cannot get between the NodeJS server and the scripts if the application is already running. Therefore to trace a Node.js 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.

You can also trace applications with ECMASript6, CoffeeScript, and TypeScript code: Spy-js recognizes source maps that set correspondence between the original code and the JavaScript code generated during compilation.

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, JetBrains Rider 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.

    • 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 on the context menu of the selection. If the traced site is mapped with a JetBrains Rider project, JetBrains Rider 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 JetBrains Rider project, JetBrains Rider 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 JetBrains Rider project, JetBrains Rider 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.

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. Specify the Node.js interpreter to use, see Configuring a local Node.js interpreter for details.
    2. The trace server port. This port number must be the same as your system proxy port. If the Automatically configure system proxy checkbox 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 checkbox 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 checkbox.

      Clear the Automatically configure system proxy checkbox 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 JetBrains Rider 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 Browse 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 Run 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 Node.js application

  1. Create a run configuration of the type Spy-js for Node.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 for Node.js on the context menu. In the Run/Debug Configuration: Spy-js for Node.js dialog box that opens, specify the following:
    1. Specify the Node.js interpreter to use, see Configuring a local Node.js interpreter for details.
    2. The Node parameters, that is, the Node.js-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. By default, the field shows the project root folder.
    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 compilation using file watchers.

    5. The application parameters: the Node.js-specific arguments to be passed to the application start file through the process.argv array.
    6. The environment variables for the Node.js 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 JetBrains Rider 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 Browse 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 checkbox 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 checkbox selected.

  2. To launch a tracing session, click Run run. The Spy-js tool and the Node.js 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 with arrow button on the Events toolbar, and then choose Save trace from the list. JetBrains Rider 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 Node.js 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 with arrow 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. To stop capturing events without stopping the application, choose Mute All. 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 instead of being removed as new events are captured. 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 Add new 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 new, 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, JetBrains Rider 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.

Choosing a filter to apply

iconFilter

Creating exclusion rules on the fly

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 JetBrains Rider, 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. The rule will be either added to the currently applied filter or a new filter will be created if the current setting is Capture All.

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.

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

Setting timestamp labels

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.

  • To set a timestamp label, choose Add Label on the context menu in the Events pane. A label Labelled at <timestamp> is added under the document node.

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

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. To navigate from an event or a script to the trace file, do one of the following:

  • 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

You can also navigate to the source file displayed as is, without prettifying.

If the traced site is mapped with a JetBrains Rider project, JetBrains Rider 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 JetBrains Rider project, JetBrains Rider opens the read-only page source, just as if you chose View Page Source in the browser.

  • 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

To navigate from a function to the place in the code where it was called from:

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

Navigating through ECMAScript 6, TypeScript, or CoffeeScript

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.

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.

Alternatively, you can navigate to the executed JavaScript code by choosing Jump to Trace.

  1. Configure the way source maps are treated by clicking cogwheel on the toolbar of the Events stack and choosing the following options on the context menu:
    • Choose Enable Source Map Look-up to enable navigation to the ECMAScript 6, TypeScript or CoffeeScript source code using the source maps generated during compilation.
    • Choose Enable source map generation, 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.
    • Choose Always open source mapped trace if available, to have Spy-js try to open the mapped trace file when you invoke navigation from an event to its caller.
  2. To navigate from a function to the source code, select the function in question in the Event Stack pane and choose one of the following options on the context menu of the selection:
    • To navigate to the ECMAScript 6, TypeScript or CoffeeScript source code, choose Jump to Source on the context menu of the selection.
    • To navigate to the JavaScript trace file, choose Jump to Trace.
    • To navigate to the mapped trace file (ECMAScript 6, TypeScript or CoffeeScript), choose Jump to Mapped Trace.
  3. To navigate from a function to its call, select the function in the Event Stack and choose Jump to Caller.
    • 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.

Advanced trace navigation

With advanced trace navigation, you can 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
spy_js_advanced_navigation_1.png
When you choose one of these actions, the cursor jumps to the call in the stack. If the Autoscroll to Trace toggle button is pressed, the corresponding trace file opens automatically with the cursor positioned at the call.

Advanced trace search

Advanced trace search lets you navigate between the calls of a function within the whole trace (across all the traced events). This means that if you are tracing 5 pages in the browser and the Events pane, accordingly, shows 5 document nodes, JetBrains Rider searches for the calls of the selected function under all these nodes and displays the number of found calls of the function in the Status bar.

The search results are reset and the search toolbar is hidden when you invoke another advanced search or navigation.

Also keep in mind that the number of call occurrences is calculated when you choose the Search this function calls across all events option. As you analyze the detected calls, the time passes, new events are captured, and the first detected call can happen to be already removed from the stack which means that it is no longer available for navigation.

  • To invoke the search for the calls of a function in all document nodes, select the function in question in the Event Stack pane and choose Search this function calls across all events on the context menu of the selection. The number of found calls is displayed in the Status bar, and the toolbar shows four previously hidden navigation chevron buttons.
    spy_js_advanced_search_1.png
  • Use the chevron buttons to navigate within the found calls:
    • To jump to the first detected call, click spy js advanced search first occurence.
    • To jump to the last detected call, click spy js advanced search last occurence
    • To jump to the next detected call, click spy js advanced search next occurence The Status bar shows a message: Occurrence <number> of <total number of detected calls>
    • To jump to the previous detected call, click spy js advanced search previous occurence.
    spy_js_advanced_search_2.png

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 Node.js 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 to a browser, the object is marked with the icon_spy_js.png icon and with the icon of this browser.

Activating Spy-js autocompletion

By default, the functionality is turned off. To activate it:

  • Click the cogwheel blue with arrow 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 Shift+F9, 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

By default, the functionality is turned off. To activate it:

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

Viewing dependency diagrams

With Spy-js, you can build and examine runtime application/event diagrams for client-side and Node.js applications.

To view the dependency diagrams

  1. Generate a diagram:
    • To build a diagram with the dependencies within the entire application, select the document node and choose Show application dependency diagram on the context menu of the selection.
    • To build a diagram with the dependencies of a single event, select the required event in the Events pane and choose Show event dependency diagram.
  2. Analyze the diagram:
    • 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 in question 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.

Last modified: 20 August 2018