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.

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 .
   The ACTIONS and METRICS menu opens.
   
2. Under METRICS, select Counter.
   The Insert a Counter configuration form opens.
   

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

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 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 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 .
   The ACTIONS and METRICS menu opens.
   
2. Under METRICS, select Tic & Toc.
   The Insert a Tic & Toc configuration form opens.
   

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

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 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 .
   The ACTIONS and METRICS menu opens.
   
2. Under METRICS, select Custom Metric.
   The Insert a Custom Metric configuration form opens.
   

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

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 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 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¶

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

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

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 icon.
   The AGENT OPTIONS menu opens.
   

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.

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