Skip to content

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 in the agent.config file (for each agent).


You must save the changes and restart the application in order to apply the new configuration.

Setting agent properties from the agent.config file

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

  1. navigate to <install_dir>/agent/agent.config on the application server and
  2. Edit the values for the relevant propertiesagent.config file.

The following table describes the agent properties that you can customize manually from the agent.config file.

Configurable agent properties in the agent.config file

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)
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.0 and 1.0) 0.1 float
max_log_cpu_cost Maximum allowed additional CPU load when logging (value between 0.0 and 1.0) 0.1 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
agent.regmetadata.file The name of the tags and metadata file agent.metadata.json string
ignore_quota Disable performance safety measures - USE WITH CAUTION 0 bool
pinned_certs 64 character sha256 certificate public key hash for pinning 515a630cfd1fb908
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
com.lightrun.DynamicLog.handlers File and error log handlers where to send logs java.util.logging.FileHandler
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
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_frame_count Maximum allowed stack frames when capturing an exception (same as for snapshot) 5 int32
exceptions_maximum_buffer_size Maximum allowed bytes when capturing an exception (same as snapshot) 655360 int32

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.

The following additional parameters can be set only from the the command line, only.

| | | | |Parameter|Explanation|Type| |---|---|---| |lightrun_extra_class_path |Additional directories and files containing resolvable binaries |string| | lightrun_init_wait_time_ms | timeout for wait iflightrun_wait_for_init is set | int32 | | lightrun_wait_for_init | Block the application until first time breakpoints are fetched from the server | bool |

Agent property environment variables must be comma-separated and inserted following the path to the agent.

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


java -agentpath:/Users/brucewayne/Downloads/agent/<PATH_TO_JAR> PrimeMain

Last update: November 24, 2021