Tuning the agent configuration¶
According to the Lightrun actions you specify, the agent dynamically inserts logs, metrics, and snapshots into the target environment. The agent's behavior when performing these tasks is governed by a set of user-configurable properties.
You can modify the agent's behavior by configuring its properties. Configuring the agent properties can be done either from the command line flags or from the
agent.config file. The agent properties are defined per agent.
Setting agent properties from the command line¶
You can flexibly set many of the available agent properties as part of the command when running your application.
Some are passed as “agent flags”, with additions to the agentpath parameter.
Others are passed as JVM flags using the -D syntax.
-agentpath:<path-to-agent>/lightrun_agent.so -D<flag>=<value> <AppName>
The example below shows both kinds of flags:
java -agentpath:/agent/lightrun_agent.so=--lightrun_extra_class_path=<PATH_TO_JAR> -Dcom.lightrun.secret=<YOUR-SECRET> <AppName>
See the tables below for details.
Setting agent properties from the
To manually set agent properties in the
- On the server where the application is running, navigate to
- In the
agent.configfile, edit the values for the relevant properties.
You must save the changes and restart the application to apply the new configuration.
Agent properties list¶
The following tables describe the agent properties that you can customize for an agent.
-D to pass these through the command line
|Parameter name||Explanation||Default value||Type|
| ||URI of the Lightrun server . The correct path is automatically inserted. Must not be modified.||None||string|
| ||Lightrun agent API key||None||char(64)|
| ||File and error log handlers where to send logs|| ||string|
| ||Specifies the name of a ||None||string|
| ||Specifies the error log file name pattern||None||string|
| ||specifies the name of a ||None||string|
| ||Specifies a pattern for generating the output log file name. "%u" is a unique number automatically assigned at runtime|| ||string|
-- to pass these through the command line
|Parameter name||Explanation||Default value||Type|
| ||Maximum allowed ratio of logs printed (the higher ratio, the more logs are allowed to be printed)||60||int32|
| ||Maximum allowed additional CPU load when inserting actions during condition evaluation (value between 0.1 and 1.0)||1.0||float|
| ||Maximum allowed additional CPU load when logging (value between 0.1 and 1.0)||1.0||float|
| ||Maximum allowed total bytes for snapshots||655360||int32|
| ||How often (in microseconds) to log debugger performance statistics. Set to zero to never log stats||3000000||int32|
| ||Time-to-live for actions||3600||int32|
| ||Time in milliseconds to pause a dynamic log after quota is reset||500||int32|
| ||Disable performance safety measures - USE WITH CAUTION||0||bool|
| ||64 character sha256 certificate public key hash for pinning||515a630cfd1fb908 |
| ||Enable personally identifiable information (PII) redaction at the agent's side (may affect the application's performance)||0||bool|
| ||Agent empties queues before the application exits.||0||bool|
| ||Maximum allowed output rate for logs (bytes per second)||204800||int32|
| ||Maximum allowed snapshot frame count||5||int32|
| ||Enable/disable certificate pinning. Setting to ||1||bool|
| ||The maximum number of action updates allowed to be transmitted in a single batch||10||int32|
| ||Enables invokedynamic instruction support||0||bool|
| ||Enables or disables Java expressions and conditions autoboxing and unboxing support. Value can either be 0 (disabled), or 1 (enabled).||1 (enabled)||bool|
Additional command line flags¶
The following flags can be set only from the command line:
| ||Additional directories and files containing resolvable binaries||string|
| ||Block the application until the first time breakpoints are fetched from the server. This option is intended for short-running applications like serverless functions, and it ensures that the Lightrun agent has time to communicate with the Lightrun server before the short-running application disconnects. |
Note - using lightrun_wait_for_init in a cloud environment will likely incur additional costs from the cloud provider due to a longer application runtime.
| ||Timeout in milliseconds for wait if ||int32|
To add multiple values to the
lightrun_extra_class_path flag, chain the values together just as you would in a regular JVM CLASSPATH environment value. Use the appropriate separator for your operating system.
The Lightrun JVM agent does not work with Java expressions and conditions whose bytecode contains Invokedynamic instructions by default. This includes expressions and conditions containing Lambda expressions and String concatenations using the ‘+’ character.
To debug these methods with Lightrun, you must enable Invokedynamic support in your JVM agent configuration.
To enable Invokedynamic instructions support¶
- Configure the
invokedynamic_enabledparameter in your agent.config file:
invokedynamic_enabled = 1
- Specify a dump folder to allow the JVM agent to read your generated Lambda classes.
To create a dump folder.
- Create a new folder, e.g., ‘/myapp/dump’.
- Add the new folder in your JVM options.
- Add the new folder to your CLASSPATH.