Tuning the agent configuration¶

According to the Lightrun actions you specify, the agent dynamically inserts logs, metrics, and snapshots into the production code. The agent's behavior when performing these tasks is governed by a set of user-configurable properties.

Agent 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 any of the available agent properties contained in agent.config as environment variables, entered from the terminal as part of the command when running your application.

Agent flags must be comma-separated and inserted following the path to the agent.

-agentpath:<path-to-agent>/lightrun_agent.so=--<parameter>=<value>,--<parameter>=<value>... <AppName>

Lightrun JVM flags are passed by using the -D prefix.

-agentpath:<path-to-agent>/lightrun_agent.so -D<flag>=<value> <AppName>

Example

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>

Setting agent properties from the `agent.config` file¶

To manually set agent properties in the agent.config file:

On the server where the application is running, navigate to <install_dir>/agent/agent.config.
In the agent.config file, edit the values for the relevant properties.

Important

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.

JVM flags¶

Info

Use -D to pass these through the command line

Parameter name	Explanation	Default value	Type
`com.lightrun.server`	URI of the Lightrun server . The correct path is automatically inserted. Must not be modified.	None	string
`com.lightrun.secret`	Lightrun agent API key	None	char(64)
`agent.regmetadata.file`	The name of the tags and metadata file	`agent.metadata.json`	string
`com.lightrun.DynamicLog.handlers`	File and error log handlers where to send logs	`java.util.logging.FileHandler` `java.util.logging.ConsoleHandler`	string
`com.lightrun.DynamicLog.ConsoleHandler.formatter`	Specifies the name of a `Formatter` class to use	None	string
`com.lightrun.DynamicLog.ConsoleHandler.pattern`	Specifies the error log file name pattern	None	string
`com.lightrun.DynamicLog.FileHandler.formatter`	specifies the name of a `Formatter` class to use	None	string
`com.lightrun.DynamicLog.FileHandler.pattern`	Specifies a pattern for generating the output log file name. "%u" is a unique number automatically assigned at runtime	`/tmp/lightrun_file_handler_logs%u.log`	string

Agent flags¶

Info

Use -- to pass these through the command line

Parameter name	Explanation	Default value	Type
`max_dynamic_log_rate`	Maximum allowed ratio of logs printed (the higher ratio, the more logs are allowed to be printed)	60	int32
`max_condition_cost`	Maximum allowed additional CPU load when inserting actions during condition evaluation (value between 0.1 and 1.0)	1.0	float
`max_log_cpu_cost`	Maximum allowed additional CPU load when logging (value between 0.1 and 1.0)	1.0	float
`max_snapshot_buffer_size`	Maximum allowed total bytes for snapshots	655360	int32
`log_stats_time_micros`	How often (in microseconds) to log debugger performance statistics. Set to zero to never log stats	3000000	int32
`breakpoint_expiration_sec`	Time-to-live for actions	3600	int32
`dynamic_log_quota_recovery_ms`	Time in milliseconds to pause a dynamic log after quota is reset	500	int32
`ignore_quota`	Disable performance safety measures - USE WITH CAUTION	0	bool
`pinned_certs`	64 character sha256 certificate public key hash for pinning	515a630cfd1fb908 e30087bcc20b7413 ad146b9bf2b23d3a aa72c28e45b24fb2	char(64)
`enable_pii_redaction`	Enable personally identifiable information (PII) redaction at the agent's side (may affect the application's performance)	0	bool
`exit_after_report_all`	Agent empties queues before the application exits.	0	bool
`longpolling_timeout_milli`		30000	int32
`max_dynamic_log_bytes_rate`	Maximum allowed output rate for logs (bytes per second)	204800	int32
`max_snapshot_frame_count`	Maximum allowed snapshot frame count	5	int32
`default_certificate_pinning_enabled`	Enable/disable certificate pinning. Setting to `false` skips certificate checking	1	bool
`transmission_bulk_max_size`	The maximum number of action updates allowed to be transmitted in a single batch	10	int32
`exceptions_monitoring_enabled`	Enable exceptions capture (might affect application performance)	0	bool
`exceptions_monitoring_stdout`	Print captured exceptions	0	bool
`exceptions_report_percentage`	Process and report a specified percentage of thrown exceptions (value between 0.0 and 1.0).	1.0	float
`exceptions_should_report_caught`	Report caught and uncaught exceptions	1	bool
`exceptions_stack_trace_depth`	Maximum allowed stack frames when capturing an exception (same as for snapshot)	5	int32
`exceptions_max_buffer_size`	Maximum allowed bytes when capturing an exception (same as snapshot)	655360	int32

Additional command line flags¶

The following flags can be set only from the command line:

Parameter	Explanation	Type
`lightrun_extra_class_path`	Additional directories and files containing resolvable binaries	string
`lightrun_wait_for_init`	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.	bool
`lightrun_init_wait_time_ms`	Timeout in milliseconds for wait if `lightrun_wait_for_init` is set.	int32

Last update: September 20, 2022