Skip to content

Snapshots in the VSCode plugin

Introduction

A snapshot is a virtual breakpoint that doesn't block your code from running. Unlike traditional breakpoint, snapshots collect the stack trace and variables without interrupting the application at all.

Once you've added a snapshot, you can view the output directly from the IDE.

Prerequisites

To use the plugin, make sure you have:

  • Attached an agent to your application
  • Installed the plugin in your local VSCode instance
  • Authenticated the VSCode plugin against your Lightrun account
  • The source code file for your running application is opened in VSCode

Adding Snapshots

To add snapshots, you must open the Insert a Snapshot and enter values for snapshot parameters.

Opening the Insert a Snapshot form

Select either of the following methods:

A. Through either the Agents or Tags tab
B. From a code line in the VSCode editor

A. Agents or Tags method:

  1. From either the Agents or Tags tab, select an agent or tag and click the Add Action icon Add Action button.
    The ACTIONS and METRICS menu opens.
    Add Action menu
  2. Under ACTIONS, select Snapshot.
    The Insert a Snapshot form opens.
    Inserting a Snapshot

B. Code line method:

  1. Go to the line in your application source code where you want to insert the snapshot.
  2. Right-click to open the VSCode context menu.
    VSCode context menu
  3. From the VSCode context menu, click Lightrun....
    The VSCode Command Palette opens with a list of Lightrun plugin options.
    Lightrun plugin command palette
  4. From the Command Palette, select Insert a Snapshot.
    The Insert a Snapshot form opens.
    Inserting a Snapshot

Entering Snapshot parameters

  1. In the Insert a Snapshot form, complete the fields, as follows:

    • TARGET
      From the available options in the dropdown list, bind the action to a specific agent or tag.
    • FILENAME & LINE
      The source code file into which you're inserting the action. The default path is to the source code file from which you're currently working.

      Tip

      Clicking the Get filename & line Get filename & line icon icon automatically loads the file name and line number at which the cursor currently is positioned within the VSCode editor.

      Use the up/down arrows to change the line number for inserting the snapshot.

    • CONDITION
      The condition of an if statement, used to limit the execution of the action.

      Example

      The condition myVar % 7 == 0 limits the action (log, snapshot, metric) output so that it only prints for variables that are divisible by 7.

    • HIT LIMIT
      The maximum number of times the snapshot should be taken during the lifetime of the action; default = 1.
    • LIFETIME
      The time after which the action ceases to track code behavior and is automatically disabled; default = 1 hour.
    • WATCH EXPRESSIONS
      Variables or method results to be displayed in the snapshot stack trace. Click + to add additional watch expressions. An expression that you define to be monitored as part of the snapshot. You can evaluate complex expressions, such as methods.
  2. Click Create to add the snapshot.

    Upon snapshot creation:

    • In the editor area, the Snapshot icon icon appears next to the selected code line.
    • In the Lightrun plugin, either the Tags or Agents tab opens and the requested agent or tag is expanded, with the Snapshot action appearing below it.

Viewing Snapshot data

After you add a snapshot to your code, and a snapshot hit is captured:

  • A notification that a snapshot was captured appears in the on the bottom right edge of the VSCode screen.
  • The snapshot variables and stack trace appear under the Snapshots tab in the Lightrun plugin.

To view Snapshot variables and stack traces:

  1. To open a snapshot, use either option A or B:

    Option A - From either the Agents, Tags, and from the list, select the relevant snapshot.
    Option B - Open the Snapshots tab and, from the list, select the relevant snapshot.

    The snapshot view window opens in the Snapshots tab.
    Snapshot data

  2. To expand the snapshot data view, click the (>) icons, next to Variables and Call Stack.

  3. To view snapshot hits within a series, click the ← and → arrows to cycle through the series or enter a snapshot hit number in the Go to hit box and click Go.
  4. To view details of a specific frame within a snapshot hit, in the Call Stack pane, click on the relevant stack trace variable or method. In the example below, the add method is selected, and the relevant variable values displayed.
    Snapshot frame

Info

Viewing snapshots from the Lightrun Management Portal is described here.

Viewing and editing a Snapshot configuration

After you have created a snapshot, you can view and edit its configuration.

  1. In the Lightrun plugin, depending on the target, select either the Agents or Tags tab.
  2. Next to the Snapshot entry, click the Snapshot Options menu icon (...) and select Details.
    The Snapshot details window opens.
    Snapshot details
  3. To edit the configuration, click the edit icon Edit icon.
    The Edit a Snapshot form opens.
  4. In the respective fields, enter new values for line number, condition, hit limit, and so on.

Last update: January 18, 2022