Skip to content

Metrics

From the Lightrun plugin for VSCode, you can add metrics to any line of your source code.

Lightrun provides three metric varieties for monitoring the performance of your code, and identifying issues:

  • Counters - Counts the number of times a specific line of code is reached
  • Tic & Toc - Measures the elapsed time between two selected lines of code within a function.
  • Custom Metrics - Create customized metrics, using parameters and simple or complex expressions that return a long int result

Once you've added the metrics, depending on how the agent's log routing is configured, you can view the output directly from the IDE, the Lightrun plugin, or the Lightrun Management Portal.

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

Support

Metrics are supported only for Java/JVM applications.

Counters

Use counters to obtain deeper insight into the behavior of your application code

The counter action counts each time a specified line of code is reached. The counter periodically logs its result to the standard logger.

Inserting a Counter

To count the number of times a line of code is reached:

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 METRICS, select Counter.
    The Insert a Counter configuration form opens.
    Inserting a Counter form

B. Code line method

  1. Go to the line in your application source code where you want to insert the counter.
  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 Counter.
    The Insert a Counter configuration form opens.
    Inserting a Counter form

Configuring a Counter

  1. In the Insert a Counter configuration 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 counter.

    • NAME
      A meaningful label for the metric.
    • 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.

    • AGGREGATED BY THREAD
      Group the metric based on thread names. Specify the required thread name prefix, followed by an asterisk.

      Example

      If you specify just *, the counter increments for all threads that reach a given line of code (the same as the default).
      If you specify mythread*, all threads with the prefix mythread are considered as a single group; the counter increments only if a member of the mythread* group reaches the given line of code.

    • LIFETIME
      The time after which the action ceases to track code behavior and is automatically disabled; default = 1 hour.
  2. Click Create to add the counter.

    Upon counter creation:

    • In the editor area, the Counter 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 Counter action appearing below it.

Tic & Toc

Inserting a Tic & Toc

To measure the elapsed time for a specified block of code, within the same function, to run:

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 METRICS, select Tic & Toc.
    The Insert a Tic & Toc configuration form opens.
    Inserting a Counter form

B. Code line method:

  1. Go to the line in your application source code where you want to insert the counter.
  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.
  4. From the Command Palette, select Insert a Tic & Toc.
    The Insert a Tic & Toc configuration form opens.
    Inserting a Counter form

Configuring a Tic & Toc

  1. Complete the fields in the Tic & Toc configuration form as follows:

    • TARGET
      From the available options in the dropdown list, bind the action to a specific agent or tag.
    • FILENAME AND LINES

      The application's file path, and the start and end lines for the code block to be timed.

    • NAME

      A meaningful label for the metric.

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

    • LIFETIME
      The time after which the action ceases to track code behavior and is automatically disabled; default = 1 hour.
  2. Click Create to add the Tic & Toc metric.

    Upon Tic & Toc creation:

    • In the editor area, the Tic&Toc 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 Tic & Toc action appearing below it.

Custom Metrics

Any expression - simple or complex - that evaluates to a numerical result can be instrumented as your very own custom metric, to be sampled over time.

Inserting a Custom Metric

To create a Custom Metric:

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 METRICS, select Custom Metric.
    The Insert a Custom Metric configuration form opens.
    Inserting a Custom Metric form

B. Code line method:

  1. Go to the line in your application source code where you want to insert the custom metric.
  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.
  4. From the Command Palette, select Insert a Custom Metric.
    The Insert a Custom Metric form opens.
    Inserting a Custom Metric form

Configuring a Custom Metric

  1. Complete the fields in the Custom Metric configuration form 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.

      Note

      Metrics (standard and custom) continue to be published every few seconds, even if the code didn't reach the code line where the metric is inserted. However, the metric result remains unchanged from the previous value.

    • NAME
      A meaningful label for the metric.
    • EXPRESSION
      An expression that returns a long int result.
    • 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.

      Note

      Metric (standard and custom) results continue to be published every few seconds, even if the condition statement is not satisfied.

    • LIFETIME
      The time after which the action ceases to track code behavior and is automatically disabled; default = 1 hour.
  2. Click Create to add the Custom Metric.

    Upon Custom Metric creation:

    • In the editor area, the Custom Metric 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 Custom Metric action appearing below it.

Viewing, disabling, and deleting a metric action

Viewing a metric action configuration

Note

Metrics cannot be edited.

To view a metric action configuration:

From the ACTION OPTIONS menu, select Details.
The metric details pane appears (details for the Tic & Toc action is shown below).
Metric details pane

Disabling a metric action

To temporarily pause output from a metric action:

  1. From the list under Actions bar, hover your cursor over the relevant action.
    A toggle switch appears.
    Action toggle switch
  2. Click the toggle switch from blue (on) to grey (off).
  3. To resume output of the metric action output, click the toggle back to blue.

Deleting a metric action

To delete a metric action, next to the action identifier, click the menu icon ... and select Delete from the ACTION OPTIONS menu.
Action Options menu

Viewing metrics output

Lightrun metrics output can be routed to the VSCode Lightrun Console, the app's standard output (Stdout), or your integrated logging tools, depending on how you have configured routing and any integrations.

To view Lightrun Logs and Metrics data from VSCode, you must configure the routing accordingly.

There are three levels of routing for output from Lightrun dynamic logs and metrics:

  • Stdout - Output appears only in the application's standard output.
  • Plugin - Output appears in the Lightrun Management Portal, Lightrun Console, and integrations.
  • Both - Output appears in the Lightrun Management Portal, Lightrun Console, integrations, and standard output.

To configure routing:

  1. From the Lightrun sidebar, choose either of the following methods.
  2. Under the Agents tab, for the relevant agent, click the More options icon.
    The AGENT OPTIONS menu opens.
    Agent options menu
  3. Choose either of the following two methods:

    Method A:
    From the Agent Options menu, under LOG ROUTING, select an options from Stdout, Plugin, or Both.

    Method B:
    1. From the Agent Options menu, under AGENT OPTIONS, select Details.
    The Agent Details window opens, with the LOG ROUTING options menu.

    Agent options menu
    2. From LOG ROUTING, select an option from Both, App only, or Plugin only.

Note

Dynamic Logs and Metrics are sent from the agent to the plugin via the Lightrun server. As this process is batched, output may appear with a slight delay.


Last update: May 18, 2022