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, no recompilation required. The agent uses bytecode instrumentation (via ASM/ByteBuddy) to hook into your running classes and connects to the HyperProbe broker over gRPC to receive probe instructions and report telemetry.
Requirements
- Java 8 or later (compiled with
-source 1.8 -target 1.8 compatibility)
- A running HyperProbe broker (URL provided by your team or HyperProbe cloud setup)
- The
hyperprobe-agent.jar file (download from your HyperProbe dashboard or CI artifact store)
- The git commit SHA of the deployed build
How the agent works
When you attach the JAR with -javaagent, the JVM calls the agent’s premain method before your application’s main method runs. The agent then:
- Reads configuration from system properties or environment variables.
- Connects to the HyperProbe broker over gRPC.
- Instruments your classes at load time using ASM/ByteBuddy bytecode transformations.
- Listens for probe instructions from the broker and captures telemetry when probed lines execute.
Your application code remains untouched. There are no annotations to add, no SDK calls to make, and no changes to your build process.
Attaching the agent
Add the -javaagent flag to your JVM startup command, followed by the required configuration as system properties:
java \
-javaagent:/opt/hyperprobe/hyperprobe-agent.jar \
-Dhyperprobe.serviceId=payment-service \
-Dhyperprobe.environment=production \
-Dhyperprobe.brokerUrl=grpc://hyperprobe-broker.internal:50051 \
-Dhyperprobe.commitSha=${GIT_COMMIT} \
-jar your-application.jar
A valid commitSha is required. The agent uses it to resolve source maps and match probe positions to the exact version of code deployed. If commitSha is missing or invalid, the agent will not activate. Set the GIT_COMMIT environment variable in your deployment pipeline and reference it as shown above.
Configuration
The Java agent reads configuration from JVM system properties (-D flags). The property names mirror the concepts from the Node.js SDK. All safety guardrail and data control values can also be set via environment variables — environment variables take precedence over system properties.
Required properties
| System property | Environment variable | Description |
|---|
hyperprobe.serviceId | — | Identifier for your service (e.g., payment-service) |
hyperprobe.environment | — | Deployment environment (e.g., production, staging) |
hyperprobe.brokerUrl | — | gRPC broker URL (e.g., grpc://broker.internal:50051) |
hyperprobe.commitSha | GIT_COMMIT | Git commit SHA of the deployed build |
Safety guardrails
| System property | Environment variable | Default | Description |
|---|
hyperprobe.hitsPerSec | HYPERPROBE_HITS_SEC | 10 | Maximum probe hits per second before the agent throttles |
hyperprobe.bandwidthKbPerSec | HYPERPROBE_BANDWIDTH_KB_SEC | 200 | Maximum telemetry bandwidth in KB/s |
hyperprobe.maxLagMs | HYPERPROBE_MAX_LAG_MS | 50 | Maximum acceptable instrumentation lag in ms before the safety shield activates |
hyperprobe.pauseBudgetMs | HYPERPROBE_PAUSE_BUDGET_MS | 20 | Maximum total pause time per second in ms |
hyperprobe.cooldownSec | HYPERPROBE_COOLDOWN_SEC | 10 | Cooldown period in seconds after the safety shield triggers |
hyperprobe.syncIntervalMs | HYPERPROBE_SYNC_INTERVAL_MS | 60000 | How often (in ms) the agent syncs probe state with the broker |
Data controls
| System property | Environment variable | Default | Description |
|---|
hyperprobe.redactKeys | HYPERPROBE_REDACT_KEYS | See below | Comma-separated list of field names to auto-redact from snapshots |
hyperprobe.redactValues | HYPERPROBE_REDACT_VALUES | — | Comma-separated list of values to redact |
hyperprobe.maxObjectDepth | HYPERPROBE_MAX_OBJECT_DEPTH | 3 | Maximum depth for serializing nested objects |
hyperprobe.maxArrayLength | HYPERPROBE_MAX_ARRAY_LENGTH | 3 | Maximum number of array elements captured |
hyperprobe.stackFrameDepth | HYPERPROBE_STACK_FRAME_DEPTH | 3 | Number of stack frames included in snapshots |
hyperprobe.maxObjectProperties | HYPERPROBE_MAX_OBJECT_PROPERTIES | 50 | Maximum number of object properties captured |
hyperprobe.maxStringLength | 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.redactKeys or HYPERPROBE_REDACT_KEYS.
Examples
java \
-javaagent:/opt/hyperprobe/hyperprobe-agent.jar \
-Dhyperprobe.serviceId=order-service \
-Dhyperprobe.environment=production \
-Dhyperprobe.brokerUrl=grpc://hyperprobe-broker.internal:50051 \
-Dhyperprobe.commitSha=${GIT_COMMIT} \
-Dhyperprobe.hitsPerSec=20 \
-Dhyperprobe.redactKeys=password,secret,token,ssn \
-jar order-service.jar
FROM eclipse-temurin:21-jre
COPY hyperprobe-agent.jar /opt/hyperprobe/hyperprobe-agent.jar
COPY order-service.jar /app/order-service.jar
ENV HYPERPROBE_HITS_SEC=20
ENV HYPERPROBE_MAX_LAG_MS=30
ENV HYPERPROBE_REDACT_KEYS=password,secret,token,ssn
ENTRYPOINT ["java", \
"-javaagent:/opt/hyperprobe/hyperprobe-agent.jar", \
"-Dhyperprobe.serviceId=order-service", \
"-Dhyperprobe.environment=production", \
"-Dhyperprobe.brokerUrl=grpc://hyperprobe-broker.internal:50051", \
"-jar", "/app/order-service.jar"]
GIT_COMMIT at runtime from your CI/CD pipeline:docker run \
-e GIT_COMMIT=$(git rev-parse HEAD) \
order-service:latest
spec:
containers:
- name: order-service
image: order-service:latest
env:
- name: GIT_COMMIT
value: "a3f92c1d"
- name: HYPERPROBE_HITS_SEC
value: "20"
- name: HYPERPROBE_REDACT_KEYS
value: "password,secret,token,ssn"
command:
- java
- -javaagent:/opt/hyperprobe/hyperprobe-agent.jar
- -Dhyperprobe.serviceId=order-service
- -Dhyperprobe.environment=production
- -Dhyperprobe.brokerUrl=grpc://hyperprobe-broker.internal:50051
- -jar
- /app/order-service.jar
Spring Boot and application servers
For Spring Boot applications using the Spring Boot Maven/Gradle plugin, add the JVM argument in your launch configuration:
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<jvmArguments>
-javaagent:/opt/hyperprobe/hyperprobe-agent.jar
-Dhyperprobe.serviceId=my-service
-Dhyperprobe.environment=production
-Dhyperprobe.brokerUrl=grpc://hyperprobe-broker.internal:50051
</jvmArguments>
</configuration>
</plugin>
bootRun {
jvmArgs = [
'-javaagent:/opt/hyperprobe/hyperprobe-agent.jar',
'-Dhyperprobe.serviceId=my-service',
'-Dhyperprobe.environment=production',
'-Dhyperprobe.brokerUrl=grpc://hyperprobe-broker.internal:50051'
]
}
For application servers like Tomcat or JBoss, add the -javaagent flag to the JAVA_OPTS or CATALINA_OPTS environment variable in your server startup script. The agent works with any standard JVM process.
