Customize the Lightrun Java agent¶

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.

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

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

Others are passed as JVM flags using the -D syntax.

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

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 agent.config file¶

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

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

Agent properties list¶

The following tables describe the agent properties that you can customize for an agent.

JVM flags¶

Agent flags¶

Additional command line flags¶

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

HTTP-Proxy configuration¶

A custom HTTP proxy server can be configured for agent traffic.

The proxy server should support the CONNECT method.

Proxy authentication is currently not supported in the Java agent for compatibility with Java 8.

The variables for HTTP proxy host and port can be provided using on of the following methods:

• Via the agent flags proxy_host and proxy_port
• Via environment variables LIGHTRUN_PROXY_HOST and LIGHTRUN_PROXY_PORT

When specifying proxy_host, provide it as host.com without a protocol (e.g., https://host.com or http://host.com should not be used).

Enabling Lightrun support for invokedynamic bytecode instruction in Java methods¶

A number of language constructs, such as Lambda functions and plus-operator string concatenation, supported in Java, Groovy, Scala, and Kotlin, are compiled into a special bytecode instruction - invokedynamic. Enabling support for the invokedynamic bytecode instruction in Lightrun requires enabling the feature in the agent.config file and specifying a dump folder for dynamically created classes. Once activated, Lightrun can process expressions or conditions containing calls to methods with the invokedynamic bytecode instruction.

An example of a Lightrun condition or experssion can be demonstrated as follows:

methodA().methodB() == methodC()

In this example, if any of the methods — methodA, methodB, or methodC include an invokedynamic bytecode instruction, Lightrun can process the condition. This includes scenarios where Lambda calls occur within their execution flow, whether immediately or recursively.

However, it is important to note this known limitation: You cannot add syntax reliant on the invokedynamic bytecode instruction directly within the condition or expression, such as Lambdas and plus-operator string concatenation. Nevertheless, when the Invokedynamic instruction is within a compiled class in your application, Lightrun conditions and expressions will be able to process it.

TO ENABLE INVOKEDYNAMIC BYTECODE INSTRUCTION SUPPORT¶

1. Configure the invokedynamic_enabled parameter in your agent.config file.

   invokedynamic_enabled = 1

2. Specify a dump folder. The process differs depending on the Java version being used.

   • For Java versions 20 and lower

     1. Specify a dump folder to allow the JVM agent to read your generated Lambda classes.
     2. Create a new folder, for example: /myapp/dump.

     3. Add the new folder in your JVM options.

        -Djdk.internal.lambda.dumpProxyClasses=/myapp/dump

     4. Add the new folder to your CLASSPATH.

        -classpath [other_classpath_items]:/myapp/dump

   • For Java versions 21 and higher

     1. Enable dumping of dynamically created Lambda classes. Note that the JVM will dump the dynamically created lambda classes to the following path:

        {projectDir}/DUMP_LAMBDA_PROXY_CLASS_FILES

        -Djdk.invoke.LambdaMetafactory.dumpProxyClassFiles=true

     2. Add the dump folder to your CLASSPATH. Note that the folder name is system-defined and cannot be altered.

        -classpath [other_classpath_items]:{projectDir}/DUMP_LAMBDA_PROXY_CLASS_FILES