Skip to content

Metrics

Overview

The Lightrun plugin for the IntelliJ IDEA provides four different metrics for monitoring the performance of your code, and identifying issues:

  • Counters - Count the number of times a specific line of code is reached
  • Tic & Toc - Measure the elapsed time between two selected lines of code within a function
  • Method Duration - Measure the elapsed time for a method to execute
  • Custom Metrics - Create customized metrics, using parameters and simple or complex expressions that return a long int result

Depending on how the agent's logs and metrics routing is configured, after adding a Lightrun metric, you can view its output from either the IDE, the Lightrun plugin and the Lightrun Management Portal, or all of the above.

Prerequisites

To use the plugin, make sure you have:

  • Installed the plugin in your local IntelliJ instance
  • Authenticated IntelliJ with your Lightrun account
  • Attached at least one agent to your app
  • Opened the source code file for the running application from the IDE

Support

Metrics are supported only for Java/JVM applications.

The following subsections describes, for each Lightrun metric, the procedures for:

  • applying a metric to your running application
  • viewing and manage output

Counters

Use Lightrun counters to obtain deeper insight into your application's behavior code, at any level of detail, from expressions and method calls to individual variables.

The Lightrun Counter stores the number of times a specified line of code is reached. The logs are periodically outputted to the standard logger.

Inserting a Counter

  1. Place your cursor at the line in your source code here you want to insert the Counter.
  2. Right-click to open the context menu.
    Context Menu -half
  3. Hover over Lightrun and, from the Metrics menu, select Counter.
    The Create Counter dialog appears.
    Adding a Counter -third
  4. Complete the fields in the dialog as follows:
    Agent - From the available options in the dropdown list, bind the action to a specific agent or tag.

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

    Name - A unique name used to distinguish between this and other counters in the printouts

    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.

  5. Click Advanced, to configure the following additional fields:

    Aggregate By (Counters only) - Aggregate the metric output data, based in thread names. Only thread names beginning with the substring entered in this field will be counted and grouped together. The (default) pattern * aggregates all threads into a single metric.

    Ignore Quota - The quota (rate limit) is configured by the agent configurations. Only users with IGNORE_QUOTA role can override the agent's quota limitation, the checkbox in the Lightrun plugin is disabled for other users.

    Expiry - The time after which the action ceases to track code behavior and is automatically disabled; default = 1 hour.

  6. Click OK to add the metric. The Counter icon icon appears in the left gutter of the editor, next to the code line where the action was added.

Time measures

There are two varieties of time measure metrics in Lightrun:

  • Method Duration
  • Tic & Toc

The Method Duration metric measures the elapsed time during the execution of a method (function), from the entry through a method call to exit from the return expression. A Method Duration metric therefore includes any nested methods within the primary called method.

The Tic & Toc metric measures the elapsed time of code execution between two specified lines, either in the main program or within a method (function). The Tic & Toc time measure includes the execution time for any methods (functions), and their nested methods, that occur between the specified start and end lines of the Tic & Tic start and end positions.

Note

The Tic (start line) and Toc (end line) both must be positioned inside the same code block. Therefore, for example, if the Tic is inserted at a given line in the main program, the Toc cannot be placed inside a method declared at a later line.

Inserting a Method duration

  1. Go to the line of your source code where the method is declared, for which you'd like to measure duration.

  2. Right-click to open the context menu.
    Context Menu -half

  3. Hover over Lightrun and, from the Metrics menu, click Method Duration.
    The Create Measure Duration dialog opens.
    Create Method Duration -third
  4. Complete the fields in the dialog as follows:
    Agent - From the available options in the dropdown list, bind the action to a specific agent or tag.

    Method - The name of the method (function) to which the Method Duration metric is to be applied.

    Name - A unique name used to distinguish between this and other counters in the printouts

    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.

  5. Click Advanced, to configure the following additional fields:
    Ignore Quota - The quota (rate limit) is configured by the agent configurations. Only users with IGNORE_QUOTA role can override the agent's quota limitation, the checkbox in the Lightrun plugin is disabled for other users.

    Expiry - The time after which the action ceases to track code behavior and is automatically disabled; default = 1 hour.

  6. Click OK to add the metric. The Duration edit -icon icon appears in the left gutter of the editor, next to the code line where the action was added.

Inserting a Tic & Toc

  1. Place your cursor at the block of source code line at which you'd like to insert the Tic & Toc.
  2. Right-click to open the context menu.
    Context Menu -half
  3. Hover over Lightun and, from the Metrics menu, click Time measure (tictoc). The Create Time Duration (tictoc) form appears.
    Adding a Time Duration metric
  4. Complete the fields in the dialog as follows:
    Agent - From the available options in the dropdown list, bind the action to a specific agent or tag.

    File - The file name and start and end line numbers

    Name - A unique name used to distinguish between this and other counters in the printouts

    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.

  5. Click Advanced, to configure the following additional fields:

    Ignore Quota - The quota (rate limit) is configured by the agent configurations. Only users with IGNORE_QUOTA role can override the agent's quota limitation, the checkbox in the Lightrun plugin is disabled for other users.

    Expiry - The time after which the action ceases to track code behavior and is automatically disabled; default = 1 hour.

  6. Click OK to add the metric. The Tic & Toc icon icon appears in the left gutter of the editor, next to the code line where the action was added.

Custom metrics

You can insert your own customized metrics expressions that evaluate to a long integer result.

Inserting a Custom Metric

  1. Go to the line of your source code at which you'd like to insert a custom metric.
  2. Right-click to open the context menu. Context Menu -half
  3. Hover over Lightrun and, from the Metrics menu, click Custom Metric.
    The Create Custom Metric dialog opens.
    Create Custom Metric -third
  4. Complete the fields in the dialog as follows:
    Agent - From the available options in the dropdown list, bind the action to a specific agent or tag.

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

    Name - A unique name used to distinguish between this and other counters in the printouts

    Expression - Simple or complex expressions that return 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.

  5. Click Advanced, to configure the following additional fields:
    Ignore Quota - The quota (rate limit) is configured by the agent configurations. Only users with IGNORE_QUOTA role can override the agent's quota limitation, the checkbox in the Lightrun plugin is disabled for other users.

    Expiry The time after which the action ceases to track code behavior and is automatically disabled; default = 1 hour.

  6. Click OK to add the Custom Metric. The Custom Metric icon Custom edit -icon appears in the left gutter of the editor, next to the code line where it the action was added.

Working with existing metrics

Once you've added a metric, you can:

  • Hover over a metrics icon in the editor gutter, to view summary information in a tooltip.
  • Right-click any icon in the gutter to delete or view details.

    Edit actions -quarter

Note

Because a metric's state is persistent during its lifetime (including between successive runs of the applications), they cannot be edited. A configuration modification requires the creating of a new metric.

Viewing metrics output

To view data from the IDE, you must configure the routing accordingly.

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

  • App/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. In the Lightrun plugin, navigate to the right-hand sidebar:

    The Sidebar
  2. From the relevant agent, click Sidebar -icon to open the Piping menu:

    Log Piping
  3. To view Lightrun Logs and Metrics from the IDE, set either the Plugin or the Both option.

Note

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

Lightrun dynamic logs and metrics, by default, are printed into the standard logging framework. This enables them to be analysed in the context of pre-existing logs or metrics, which might provide further clues towards solving issues.

At the same time, you can see dynamic and metrics output and, from your IDE's terminal window and search and filter, as you work. To do this, first configure logs and metrics routing for each agent. Once configured, all relevant information from any Lightrun logs or metrics, which are are added to an agent, appears in the the IDE terminal.

Viewing logs and metrics from the IntelliJ Lightrun plugin

Once you've configured routing for the plugin and added at least one action to the code, dynamic logs and metrics begin updating within the Lightrun Console, in real time.

The Lightrun Console

You can control the display of logs in the IDE using any combination of the following options:

  • Use the filters at the top right of the Lightrun Console to filter the dynamic logs or metrics relevant to your investigation.
  • In the search bar at the top left, start typing to search dynamically for dynamic logs or metrics by name.
  • To free memory or remove items already viewed, click Clear.

Last update: May 18, 2022