HyperProbe Java Agent: Installation and Setup Guide

The HyperProbe Java agent is a standard JVM instrumentation agent. You attach it to your application at startup with the -javaagent JVM flag — no code changes, no framework wrappers, and no recompilation required.

Prerequisites

Java 11 or later (compatible with standard JVMs)
A running HyperProbe broker (URL provided by your team or HyperProbe cloud setup)
The hyperprobe-agent.jar file (downloaded from your HyperProbe dashboard or CI artifact store)
The git commit SHA of the deployed build (required for coordinate resolution)

How the agent works

When you attach the JAR with -javaagent, the JVM calls the agent’s initialisation sequence before your application’s main method runs. To ensure zero interference with your application, the agent:

Starts in an isolated, child-first classloader (preventing dependency conflicts).
Reads configuration strictly from environment variables.
Connects to the HyperProbe broker over gRPC.
Instruments your classes at load time using non-intrusive bytecode transformations.
Listens for probe instructions and captures telemetry when probed lines execute.

Your application code remains entirely untouched. There are no annotations to add, no SDK methods to call, and no changes to your build process.

Attaching the agent

Add the -javaagent flag to your JVM startup command. The Java agent requires configuration to be passed via environment variables to prevent configuration leakage into the host application and to adhere to twelve-factor app principles.

export GIT_COMMIT=$(git rev-parse HEAD)
export HYPERPROBE_SERVICE_ID=uuid-of-the-service-from-dashboard
export HYPERPROBE_ENVIRONMENT=production
export HYPERPROBE_BROKER_URL=https://logger.app.hyperprobe.co

java -javaagent:/opt/hyperprobe/hyperprobe-agent.jar -jar your-application.jar

A valid GIT_COMMIT is strictly required. The agent uses it to match probe positions to the exact version of the code deployed. If GIT_COMMIT is missing, empty, or set to "unknown", the agent logs a critical error and refuses to start.

Configuration

The agent reads configuration exclusively from environment variables. System properties (-D flags) are intentionally ignored by the agent to ensure strict isolation.

Required variables

Environment variable	Description
`HYPERPROBE_SERVICE_ID`	Identifier for your service (e.g., `uuid of the service from the dashboard`)
`HYPERPROBE_ENVIRONMENT`	Deployment environment (e.g., `production`, `staging`)
`HYPERPROBE_BROKER_URL`	gRPC broker URL (e.g., `https://logger.app.hyperprobe.co`)
`GIT_COMMIT`	Git commit SHA of the deployed build

Safety guardrails

The Java agent continuously monitors JVM memory health. If free memory drops below 15%, the agent enters a YELLOW state (warning). If free memory drops below 5%, the agent enters a RED state, immediately suspending all instrumentation to protect the host application. Instrumentation automatically resumes after the HYPERPROBE_COOLDOWN_SEC period if memory levels stabilize.

Environment variable	Default	Description
`HYPERPROBE_HITS_PER_SEC`	`20`	Maximum probe hits per second globally before the agent throttles
`HYPERPROBE_BANDWIDTH_KB_PER_SEC`	`1024`	Maximum telemetry bandwidth in KB/s
`HYPERPROBE_COOLDOWN_SEC`	`10`	Cooldown period in seconds after the memory safety shield triggers
`HYPERPROBE_SYNC_INTERVAL_MS`	`60000`	How often (in ms) the agent syncs probe state with the broker
`HYPERPROBE_FLUSH_INTERVAL_MS`	`1000`	How often (in ms) the agent flushes the telemetry queue to the broker

Data controls

Environment variable	Default	Description
`HYPERPROBE_REDACT_KEYS`	See below	Comma-separated list of field names to auto-redact from snapshots
`HYPERPROBE_REDACT_VALUES`	—	Comma-separated list of values to redact
`HYPERPROBE_MAX_OBJECT_DEPTH`	`3`	Maximum depth for serializing nested objects
`HYPERPROBE_MAX_ARRAY_LENGTH`	`3`	Maximum number of array elements captured
`HYPERPROBE_STACK_FRAME_DEPTH`	`3`	Number of stack frames included in snapshots
`HYPERPROBE_MAX_OBJECT_PROPERTIES`	`50`	Maximum number of object properties captured
`HYPERPROBE_MAX_STRING_LENGTH`	`1024`	Maximum string length before truncation

The default redacted keys are: password, secret, token, authorization, cookie, key, signature. These are applied automatically. Add your own sensitive field names via HYPERPROBE_REDACT_KEYS to override the defaults.

Optional configuration

Environment variable	Default	Description
`HYPERPROBE_DISABLED`	—	Set to `YES` to completely skip agent initialization at startup
`HYPERPROBE_APP_ROOT`	—	Defines the root package or directory to restrict instrumentation scanning

Examples

Docker
Kubernetes

When deploying via Docker, it is best practice to bake the GIT_COMMIT directly into the image during the build process using build arguments, along with your static configuration.

Dockerfile

FROM eclipse-temurin:21-jre

# Define a build argument for the commit SHA
ARG GIT_COMMIT

COPY hyperprobe-agent.jar /opt/hyperprobe/hyperprobe-agent.jar
COPY order-service.jar /app/order-service.jar

# Bake the dynamic commit and static config into the image
ENV GIT_COMMIT=${GIT_COMMIT}
ENV HYPERPROBE_SERVICE_ID=order-service
ENV HYPERPROBE_ENVIRONMENT=production
ENV HYPERPROBE_BROKER_URL=https://logger.app.hyperprobe.co

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

Pass the build argument when building the image in your CI/CD pipeline:

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

Because the commit is baked in, you can run the container cleanly without runtime variables:

docker run order-service:latest

For Kubernetes deployments, define the environment variables directly within your Pod spec or Deployment manifest.

deployment.yaml

spec:
  containers:
    - name: order-service
      image: order-service:latest
      env:
        - name: GIT_COMMIT
          value: "a3f92c1d"
        - name: HYPERPROBE_SERVICE_ID
          value: "order-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/order-service.jar

Framework integrations

The agent hooks into the standard JVM initialization process, so it works seamlessly alongside any Java framework. Provide the -javaagent flag as a standard JVM argument in your build or run tasks.

Spring Boot (Maven)
Spring Boot (Gradle)
Application Servers

When running via the Spring Boot Maven plugin, provide the agent path in <jvmArguments> and set configuration in <environmentVariables>.

pom.xml

<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
  <configuration>
    <jvmArguments>-javaagent:/opt/hyperprobe/hyperprobe-agent.jar</jvmArguments>
    <environmentVariables>
      <HYPERPROBE_SERVICE_ID>my-service</HYPERPROBE_SERVICE_ID>
      <HYPERPROBE_ENVIRONMENT>production</HYPERPROBE_ENVIRONMENT>
      <HYPERPROBE_BROKER_URL>https://logger.app.hyperprobe.co</HYPERPROBE_BROKER_URL>
      <!-- In practice, you might populate this from the git-commit-id-plugin -->
      <GIT_COMMIT>${git.commit.id}</GIT_COMMIT>
    </environmentVariables>
  </configuration>
</plugin>

For Gradle’s bootRun task, specify the JVM arguments and inject the environment variables.

build.gradle

bootRun {
  jvmArgs = ['-javaagent:/opt/hyperprobe/hyperprobe-agent.jar']
  
  environment 'HYPERPROBE_SERVICE_ID', 'my-service'
  environment 'HYPERPROBE_ENVIRONMENT', 'production'
  environment 'HYPERPROBE_BROKER_URL', 'https://logger.app.hyperprobe.co'
  environment 'GIT_COMMIT', project.findProperty('gitCommit') ?: 'unknown'
}

For application servers like Tomcat, JBoss, or WildFly, add the -javaagent flag and export the necessary environment variables in your server’s startup script (e.g., setenv.sh).

bin/setenv.sh

export HYPERPROBE_SERVICE_ID=my-service
export HYPERPROBE_ENVIRONMENT=production
export HYPERPROBE_BROKER_URL=https://logger.app.hyperprobe.co
export GIT_COMMIT=$(git rev-parse HEAD)

export JAVA_OPTS="$JAVA_OPTS -javaagent:/opt/hyperprobe/hyperprobe-agent.jar"

​Prerequisites

​How the agent works

​Attaching the agent

​Configuration

​Required variables

​Safety guardrails

​Data controls

​Optional configuration

​Examples

​Framework integrations

Prerequisites

How the agent works

Attaching the agent

Configuration

Required variables

Safety guardrails

Data controls

Optional configuration

Examples

Framework integrations