Attaching and running the JVM Agent with your application¶
The Lightrun agent is at the core of the Lightrun platform. It's the component that enables you to add Lightrun actions at runtime, without redeployments or restarts.
The instructions below are geared towards Java developers working with JDK 8+. If you're interested in using Lightrun with Scala or Kotlin, please reach out and let us know!
If you haven't yet done so during the onboarding process, download the Lightrun JVM Agent from the Management Portal.
To download the agent:
- Log in to the Management Portal.
Copy the download script from the Install the Agent section:
Open a terminal and change to the directory where your project folder is located.
- Enter the copied script, from step 2. The agent downloads.
The video, below, shows what the agent download procedure looks like:
JVM Agent download process
To attach the agent to your application:
On completion of the agent download, from your terminal, enter the following command:
java -agentpath:<path-to-agent>\lightrun_agent.so -jar <your-jar-file> RestofArgumentsHere
Replace the placeholders in the command as follows:
<path-to-agent>- The full path to the agent's folder (~/ will not work)
<your-jar-file>- The full path to the application to be run with the agent
RestofArgumentsHere- Any relevant configuration options.
See the example in this video:
To cause all launched Java processes automatically to be attached to an agent, you can add the
JAVA_OPTS environment variable.
From the server terminal, enter the following command (replace the
agentpath value with the path to the Lightrun agent, after it has been downloaded):
You can customize the agent configuration at any time. To apply the changes, the application must be restarted. For further details, see here.