Lightrun actions¶

Actions are any of the snapshots, logs or metrics that you add to your applications directly from specific lines of code.

From the IDE, you can:

add the Lightrun action you need directly inline from your code

configure logs

create snapshots (breakpoints)

configure metrics

Note

A system quota controls use of CPU, Networking, Memory, excessively long strings, too many instructions printing out, protection from infinite loops and the like

Prerequisites

To use the plugin, make sure:

You've attached at least one agent to your app

You install the plugin in your local IntelliJ instance)

You authenticate IntelliJ with your Lightrun account

To add a Lightrun action

Go to the line in your code that you need to debug.
Right-click to open the IntelliJ context menu:
Hover over the Lightrun option at the top of the menu to open the sub-menu:
Now, choose your action:
- configure logs
- create snapshots (breakpoints)
- configure metrics

Logs¶

You can add logs directly to your application while it's running.

To add a log

Go to the line of your source code at which you'd like to insert the log.
Right-click to open the IntelliJ context menu:
Open the Lightrun context menu:
Select Log from the Lightrun context menu.

The Create Log dialog opens:
Complete the fields in the dialog as follows:
- Agent
  bind the action to a specific agent or tag from the available options in this dropdown list
- File
  this is the source code file into which you're inserting the action
- Format - the actual log string; use expressions such as My variable is {var} including even method invocations such as: Method value: {myMethod() + 5}
- Log Level - Debug, Info, Warning or Error; once configured, logs can also be filtered by this attribute
- Condition
  an expression that limits the action; this is the condition of an if statement used to limit the execution of the action
```
!!! example

    `myVar % 7 == 0` limits the log so it only prints for variables that are divisible by 7
```
Click Advanced to configure the following additional fields:
- Ignore quotas
  
  the quota (rate limit) is configured in the agent configuration file. Ignore Quotas defaults to off. Only users assigned the IGNORE-QUOTA role can perform this configuration; the checkbox is disabled for other users.
- Expiry
  
  the time after which Lightrun ceases to track this action; defaults to 1 hour if not configured
Click OK to add the log. A marker is also added to the area above the line:

Tip

Customize your profile picture as it appears in the marker at gravatar.com
Click from the log marker to delete or edit the log configuration.

Snapshots¶

A snapshot is a one-time "breakpoint" that doesn't block your code from running; as opposed to a traditional breakpoint, snapshots collect the stack trace and variables without interrupting the application at all.

To add a snapshot

Go to the line of your source code at which you'd like to insert the snapshot.
Right-click to open the context menu:
Select Snapshot:

The Create Snapshot dialog opens:
Complete the fields in the dialog as follows:
- Agent
  bind the action to a specific agent or tag from the available options in this dropdown list
- File
  this is the source code file into which you're inserting the action
- Expression
  variables or method results to be displayed in the stack trace of the snapshot; click + to enter additional expressions
- Condition
  an expression that limits the action; this is the condition of an if statement used to limit the execution of the action
```
!!! example

    `myVar % 7 == 0` limits the log so it only prints for variables that are divisible by 7
```
Click Advanced to configure the following additional fields:
- Max Hit Count
  
  the maximum number of times the snapshot should be taken during the lifetime of the action; default == 1.
- Ignore quotas
  
  the quota (rate limit) is configured in the agent configuration file. Ignore Quotas defaults to off. Only users assigned the IGNORE-QUOTA role can perform this configuration; the checkbox is disabled for other users.
- Expiry
  
  the time after which Lightrun ceases to track this action; defaults to 1 hour if not configured
Click OK to add the log. A marker is also added to the area above the line:

The snapshot is added and displayed in the bottom sidebar, and an icon is added to the margins of the code on the line where it was added.

The Snapshot view is further detailed here
Click from the log marker to delete or edit the log configuration.

Metrics¶

You can add the following metrics to be tracked per line in your code:

Counters and time measures - count the number of times a specific line of code throws an exception

Measure Duration

Custom Metrics

Counters and time measures¶

The counter action counts every time the given line was reached and periodically logs that information to the standard logger.

Similarly, you can add a time duration metric to measure the amount of time the specified code block runs, and then use this data to help investigate issues, track performance trouble or compare to other lines of code.

To add a counter

Go to the line of your source code at which you'd like to insert the snapshot.
Right-click to open the context menu:
Hover over Metrics and then click Counter or Time Measure (tictoc) from its sub-menu.

The Create Counter appears as follows:

The Create Time Duration (tictoc) appears as follows:
Complete the fields in the dialog as follows:
- Agent
  bind the action to a specific agent or tag from the available options in this dropdown list
- File
  this is the source code file into which you're inserting the action
- Name
  a unique name used to distinguish between this and other counters in the printouts
- Condition
  an expression that limits the action; this is the condition of an if statement used to limit the execution of the action
```
!!! example

    `myVar % 7 == 0` limits the log so it only prints for variables that are divisible by 7
```
Click Advanced to configure the following additional fields:
- Aggregate By (Counters only) - collect and aggregate data only for the referenced string
- Ignore quotas
  
  the quota (rate limit) is configured in the agent configuration file. Ignore Quotas defaults to off. Only users assigned the IGNORE-QUOTA role can perform this configuration; the checkbox is disabled for other users.
- Expiry
  
  the time after which Lightrun ceases to track this action; defaults to 1 hour if not configured
Click OK to add the metric. A marker is also added to the margins of the code on the line where it was inserted.
Click to delete or edit the counter configuration. Click to delete or edit the time measure metric configuration.

//: # ### Set value {#_set_value}

//: # One trick in debugging is to set a variable to a different value and force a specific code path. This can be particularly useful when patching broken behavior.

//: # !!! example //: # If a feature fails and it's surrounded by an if statement, you might be able to disable that feature by forcing the value of a variable.

//: # !!! warning //: # This is an extremely risky action, and as such only users with the set-value role can execute it.

//: # ###### To add a set value action

//: # 1. Go to the line of your source code at which you'd like to set a value.

//: # 2. Right-click to open the context menu:

//: #

//: # 3. Hover over Metrics and then click Set Value.

//: # 4. Enter the relevant variable name for the left-side argument. Please notice that the left hand side must be a variable in context and can't be a method.

//: # 5. In the right-side field, enter the assigned value. Valid values include any Java expression, including a method invocation.

//: # 6. You can use the + button to add additional assignments

//: # 7. Click Ok to set the action.

//: # !!! important

//: # Quotas aren't imposed on set-value operations and as such the performance impact can be significant.

Measure duration¶

Go to the line of your source code for which you'd like to measure duration.
Right-click to open the context menu:
Hover over Metrics and then click Method Duration.

The Create Measure Duration dialog opens:
Complete the fields in the dialog as follows:
- Agent
  bind the action to a specific agent or tag from the available options in this dropdown list
- Method -
- Name
  a unique name used to distinguish between this and other counters in the printouts
- Condition
  an expression that limits the action; this is the condition of an if statement used to limit the execution of the action
```
!!! example

    `myVar % 7 == 0` limits the log so it only prints for variables that are divisible by 7
```
Click Advanced to configure the following additional fields:
- Ignore quotas
  
  the quota (rate limit) is configured in the agent configuration file. Ignore Quotas defaults to off. Only users assigned the IGNORE-QUOTA role can perform this configuration; the checkbox is disabled for other users.
- Expiry
  
  the time after which Lightrun ceases to track this action; defaults to 1 hour if not configured
Click OK to add the metric. An icon is added to the margins of the code on the line where it was added.
Click from the log marker to delete or edit the log configuration.

Custom metrics¶

You can insert your own customized metrics using regular expressions.

To insert a custom metric

Go to the line of your source code at which you'd like to insert custom metrics.
Right-click to open the context menu:
Hover over Metrics and then click Custom Metric.

The Create Custom Metric dialog opens:
Complete the fields in the dialog as follows:
- Agent
  bind the action to a specific agent or tag from the available options in this dropdown list
- File
  this is the source code file into which you're inserting the action
- Name
  a unique name used to distinguish between this and other counters in the printouts
- Expression
  variables or method results to be displayed in the stack trace of the snapshot; click + to enter additional expressions
- Condition
  an expression that limits the action; this is the condition of an if statement used to limit the execution of the action
```
!!! example

    `myVar % 7 == 0` limits the log so it only prints for variables that are divisible by 7
```
Click Advanced to configure the following additional fields:
- Ignore quotas
  
  the quota (rate limit) is configured in the agent configuration file. Ignore Quotas defaults to off. Only users assigned the IGNORE-QUOTA role can perform this configuration; the checkbox is disabled for other users.
- Expiry
  
  the time after which Lightrun ceases to track this action; defaults to 1 hour if not configured
Click OK to add the log. An icon is added to the margins of the code on the line where it was added.
Click to delete or edit the counter configuration.

Edit and delete actions¶

Once you create an action, the relevant icon appears in the gutter of your code, similar to the following:

Plugin gutter -quarter

Hover over the relevant icon to read its tooltip.
Right-click the icon for other relevant options.
To view notifications, errors, etc., select Info to learn more.
To update or change the action, click Edit.
To remove the action, click Delete.

Last update: April 7, 2021