Skip to content

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.

Version Support

The instructions below are geared towards Java developers working with JDK 8+.

  • Instructions on how to setup Lightrun with Kotlin can be found here.
  • Instructions for Scala can be found here.

System requirements

Please check the JVM agent system requirements here.

Alpine Support

To use the Lightrun Java agent on an Alpine operating system, ensure libstdc++ is installed on the system.

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:

    Get the Lightrun JVM Agent
    Get the Lightrun JVM Agent

  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:

Running your application with the Lightrun Agent

Optional

To cause all launched Java processes automatically to be attached to an agent, you can add the JAVA_OPTS environment variable.
From the terminal, enter the following command (replace the agentpath value with the path to the Lightrun agent):

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

Info

You can customize the agent configuration at any time. To apply the changes, the application must be restarted. For further details, see here.

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.

Info

When getting the Lightrun agent, make sure you select the correct OS based on the OS of your base image. If, for example, you're using openjdk:17-alpine in the FROM line of your image, you should use the Lightrun alpine agent.

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.

Info

if you cannot see the agent in your plugin or the management portal, please use the troubleshooting guide or contact us.

Optional

To cause all launched Java processes automatically to be attached to an agent, you can add the JAVA_OPTS environment variable.
From the terminal, enter the following command (replace the agentpath value with the path to the Lightrun agent, after it has been downloaded):

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

Info

You can customize the agent configuration at any time. To apply the changes, the application must be restarted. For further details, see here.

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.

    Run/Debug Configurations

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

    Add VM Options

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: September 27, 2023