Java Agent Setup Guide

The HyperProbe Java Agent is a zero-touch JVM Instrumentation agent. By attaching the JAR at startup via the standard -javaagent flag, it intercepts and transforms application bytecode on-the-fly—requiring zero code changes, zero annotation wrappers, and zero compilation modifications.

Technical Prerequisites

Runtime: Java 11 or later (compatible with Oracle HotSpot, OpenJDK, Corretto, Temurin).
Metadata: Active git commit SHA (mandatory for resolving bytecode offsets to local lines).
Agent Jar: The hyperprobe-agent.jar artifact. You can view and download all releases from Maven Central (Sonatype).

Downloading the Agent

Before attaching the agent, download the hyperprobe-agent.jar file. You can fetch it directly using curl or wget (be sure to replace <LATEST_VERSION> with the current version from Maven Central):

curl

curl -L -o hyperprobe-agent.jar "https://repo1.maven.org/maven2/co/hyperprobe/hyperprobe-agent/<LATEST_VERSION>/hyperprobe-agent-<LATEST_VERSION>.jar"

wget

wget -O hyperprobe-agent.jar "https://repo1.maven.org/maven2/co/hyperprobe/hyperprobe-agent/<LATEST_VERSION>/hyperprobe-agent-<LATEST_VERSION>.jar"

Installation & Deployment

Attach the agent at startup using the standard -javaagent flag. To adhere to twelve-factor principles and prevent configuration leakage, the Java agent reads setup parameters exclusively from environment variables.

# 1. Export deployment metadata
export GIT_COMMIT=$(git rev-parse HEAD)
export HYPERPROBE_SERVICE_ID=billing-service
export HYPERPROBE_ENVIRONMENT=production # Your environment name (e.g. dev, staging, production). Use whatever variable contains the env value.
export HYPERPROBE_BROKER_URL=https://logger.app.hyperprobe.co

# 2. Attach JVM Agent at runtime
java -javaagent:/opt/hyperprobe/hyperprobe-agent.jar -jar your-application.jar

System parameters (like -Dhyperprobe.serviceUrl=...) are intentionally ignored by the agent to maintain strict classloader isolation between your application and the debugger agent. Always use environment variables.

Deployment Templates

Docker Multi-Stage Build
Kubernetes Manifest

It is best practice to download the agent jar during build-time and bake the Git commit into the final image:

Dockerfile

FROM eclipse-temurin:21-jre

# Define build arguments
ARG GIT_COMMIT
ENV GIT_COMMIT=${GIT_COMMIT}

# Setup agent directories
RUN mkdir -p /opt/hyperprobe
COPY hyperprobe-agent.jar /opt/hyperprobe/hyperprobe-agent.jar
COPY build/libs/app.jar /app/app.jar

# Inject static environment configuration
ENV HYPERPROBE_SERVICE_ID=billing-service
ENV HYPERPROBE_ENVIRONMENT=production
ENV HYPERPROBE_BROKER_URL=https://logger.app.hyperprobe.co

ENTRYPOINT ["java", "-javaagent:/opt/hyperprobe/hyperprobe-agent.jar", "-jar", "/app/app.jar"]

Build the image in your pipeline by passing the active commit:

docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) -t app:latest .

Expose your environment parameters inside your deployment’s spec definition:

deployment.yaml

spec:
  containers:
    - name: billing-service
      image: billing-service:latest
      env:
        - name: GIT_COMMIT
          valueFrom:
            configMapKeyRef:
              name: build-metadata
              key: commit-sha
        - name: HYPERPROBE_SERVICE_ID
          value: "billing-service"
        - name: HYPERPROBE_ENVIRONMENT
          value: "production"
        - name: HYPERPROBE_BROKER_URL
          value: "https://logger.app.hyperprobe.co"
      command: ["java", "-javaagent:/opt/hyperprobe/hyperprobe-agent.jar", "-jar", "/app/app.jar"]

🛠️ Build-Tool & Framework Setup

Attach the JVM agent inside your development environment to test probes locally before deploying.

Gradle (Kotlin DSL)
Gradle (Groovy DSL)
Maven (pom.xml)

Add the agent args to your standard Spring Boot run tasks inside build.gradle.kts:

build.gradle.kts

tasks.withType<org.springframework.boot.gradle.tasks.run.BootRun> {
  // 1. Add JVM Agent argument
  jvmArgs("-javaagent:${rootDir}/libs/hyperprobe-agent.jar")
  
  // 2. Inject environment parameters
  environment("HYPERPROBE_SERVICE_ID", "billing-service")
  environment("HYPERPROBE_ENVIRONMENT", "local")
  environment("HYPERPROBE_BROKER_URL", "https://logger.app.hyperprobe.co")
  environment("GIT_COMMIT", project.findProperty("gitCommit") ?: "unknown")
}

build.gradle

bootRun {
  jvmArgs = ["-javaagent:${rootDir}/libs/hyperprobe-agent.jar"]
  
  environment "HYPERPROBE_SERVICE_ID", "billing-service"
  environment "HYPERPROBE_ENVIRONMENT", "local"
  environment "HYPERPROBE_BROKER_URL", "https://logger.app.hyperprobe.co"
  environment "GIT_COMMIT", project.findProperty("gitCommit") ?: "unknown"
}

pom.xml

<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
  <configuration>
    <jvmArguments>-javaagent:${project.basedir}/libs/hyperprobe-agent.jar</jvmArguments>
    <environmentVariables>
      <HYPERPROBE_SERVICE_ID>billing-service</HYPERPROBE_SERVICE_ID>
      <HYPERPROBE_ENVIRONMENT>local</HYPERPROBE_ENVIRONMENT>
      <HYPERPROBE_BROKER_URL>https://logger.app.hyperprobe.co</HYPERPROBE_BROKER_URL>
      <GIT_COMMIT>${git.commit.id}</GIT_COMMIT>
    </environmentVariables>
  </configuration>
</plugin>

Memory Safety Shields

Because bytecode injection could theoretically impact Heap health on heavy memory spikes, the Java Agent includes an active Memory Guardrail:

Yellow Threshold (Free Memory < 15%): Logs a warning and paces serialization buffers.
Red Threshold (Free Memory < 5%): Instantly uninstalls and suspends all in-memory probes to shield your JVM from Out-Of-Memory (OOM) failures.
Auto-Recovery: Resumes instrumentation automatically once GC recovers memory health and active cooldown cycles end.

Get Started

AI-Native Debugging

VS Code Extension

SDK Integration

Probe Types

Guides

Troubleshooting

Self-Hosting

Java Agent Setup Guide

Technical Prerequisites

Downloading the Agent

Installation & Deployment

Deployment Templates

🛠️ Build-Tool & Framework Setup

Memory Safety Shields

​Technical Prerequisites

​Downloading the Agent

​Installation & Deployment

​Deployment Templates

​🛠️ Build-Tool & Framework Setup

​Memory Safety Shields

Technical Prerequisites

Downloading the Agent

Installation & Deployment

Deployment Templates

🛠️ Build-Tool & Framework Setup

Memory Safety Shields