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 communicates requests for runtime observability to your running code, and gathers and relays the requested data back to the Lightrun Server, and eventually the developer's IDE.

Before running the agent, it must be installed on the system where your code to be monitored is running, and its credentials must be declared either inside an agent.config file, or as environment variables entered from the command line.

apk add libstdc++

Lightrun can be run either directly, inside a Docker container or using the IntelliJ IDE.

In order to install Lightrun we must first get the Lightrun agent.

Getting the Lightrun Agent¶

If you haven't yet done so, please sign up for a Lightrun account.

Our onboarding flow will direct you to download the agent. You can also download the Lightrun JVM Agent from the Management Portal.

To download the agent:

1. Log in to the Management Portal.

2. Copy the download script from the Install the Agent section:

   

3. Open a terminal and navigate to the directory where your project folder is located.

4. Paste the copied script into your terminal and click the enter or return key to download.

Now that you have downloaded the agent, you can proceed to use it.

Run directly¶

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:

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

Run with Docker¶

Docker containers are ephemeral.

If you were to create a shell into a Docker container (by docker exec -it <container-id>, for example) and add the Lightrun files there, they would disappear the next time the container would spin up due to the ephemeral nature of that container.

Instead, we suggest you install Lightrun by adding it to the underlying Docker image directly, i.e. by "baking" the agent into the image.

Please see below an example of adding the Lightrun Agent into Dockerfile:

FROM openjdk:11

WORKDIR /opt/lightrun
ENV LIGHTRUN_KEY=<LIGHTRUN_KEY>
RUN bash -c "$(curl -L "https://app.lightrun.com/public/download/company/<ORG-ID>/install-agent.sh?platform=<your-base-image-os>")"

COPY prime.jar /app/prime.jar

CMD ["java", "-agentpath:/opt/lightrun/agent/lightrun_agent.so", "-jar", "/app/prime.jar"]

A few important notes:

1. Please make sure that the agent folder is located in the Docker image build path, i.e. it is present in the current working directory when you're running docker build . -t <image-name>.
2. Note the <LIGHTRUN_KEY> environment variable - it is available from the Lightrun Management Console under the "Install an Agent" section. Do note that for production use, it's a good idea to persist that secret in an external secret managment solution, like HashiCorp Vault.

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

Run with IntelliJ¶

You can attach the agent also when running your application from IntelliJ:

1. Go to the Run/Debug Configuration of your application.

2. Add the following agent argument to the VM options field:

   -agentpath:/path/to/agent/lightrun_agent.so
   

   Replace the agentpath value with the path to the Lightrun agent.

   

   If the VM options field is not available, choose Modify options and add the field: