Attaching and running the JVM Agent with your Kotlin application¶

Version Support

The instructions below apply to Kotlin v1.5 and higher.

Prerequisites

Before running the app with the agent, make sure you have:

Installed the Kotlin command-line compiler.
Downloaded the Java agent.

Running the Lightrun agent¶

For Kotlin v1.6 and higher:

Compile your application

kotlinc <your-main>.kt -include-runtime -d myapp.jar

Run the application with the Java agent
```
java -agentpath:<path-to-agent>/lightrun_agent.so -jar myapp.jar
```
For Kotlin v1.5 you might get a "no main manifest attribute". You can put the kotlin-stdlib in your classpath instead.
Compile your application
```
kotlinc <your-main>.kt
```

Run the application with the Java agent and kotlin-stdlib in your classpath

java -cp <path-to-kotlin>/kotlin-stdlib/1.4.20/kotlin-stdlib-1.4.20.jar:. -agentpath:<path-to-agent>/agent/lightrun_agent.so <your-main>

Optional

You can also automatically attach an agent to your launched Java processes with the JAVA_OPTS environment variable.

export JAVA_OPTS=-agentpath:<path-to-agent>/lightrun_agent.so

Note

Kotlin expressions are limited:

All functions in the expression should be converted to their Java equivalent. For example, (pow -> Math.pow).
Expressions with Kotlin ranges and Coroutines are not supported.

Important

Most Java compilers exclude debugging symbols by default to reduce the generated binary size and improve performance and optimization. This action can prevent Lightrun from working as the Lightrun agent needs to find several symbols, including your project's variables, to insert Lightrun actions into your project.

To ensure that the required debugging information is included in your compiled files, you must add the following debug options to your Java compiler.

-g:source
-g:lines
-g:vars

You can learn more about the debugging symbols here. For more information on specifying debugging symbols in your Maven or Gradle project, see Build tools (Maven and Gradle)

Note - The added debug options do not impact compiler optimization or performance; they only enhance the bytecode with additional debug information.

Last update: May 29, 2023