Java SDK 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 17 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. Set the required environment variables before starting your application.

# 1. Export deployment metadata
export GIT_COMMIT=$(git rev-parse HEAD)
export HYPERPROBE_SERVICE_ID="<service-uuid-from-dashboard>"
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

Use environment variables for service, broker, and capture configuration. JVM system properties do not replace these settings. Custom trace ID hooks also support the system properties listed in the configuration reference.

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="<service-uuid-from-dashboard>"
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: "<service-uuid-from-dashboard>"
        - 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", "<service-uuid-from-dashboard>")
  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", "<service-uuid-from-dashboard>"
  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>YOUR_SERVICE_UUID</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>

Configuration and environment variables

The following example lists all supported runtime environment variables. Required values are examples; optional numeric and redaction settings show their defaults.

# --- CORE OPTIONS (required strings) ---
export GIT_COMMIT=$(git rev-parse HEAD)           # Commit used to build the deployed application
export HYPERPROBE_SERVICE_ID="<service-uuid-from-dashboard>"
export HYPERPROBE_ENVIRONMENT=production         # Your environment name; no default
export HYPERPROBE_BROKER_URL=https://logger.app.hyperprobe.co

# --- BUFFERING & PERFORMANCE (integers) ---
export HYPERPROBE_FLUSH_INTERVAL_MS=1000         # Telemetry export interval in milliseconds
export HYPERPROBE_SYNC_INTERVAL_MS=60000         # Probe sync interval in milliseconds

# --- SAFETY GUARDRAILS (integers) ---
export HYPERPROBE_HITS_PER_SEC=20                # Agent-wide probe execution limit per second
export HYPERPROBE_BANDWIDTH_KB_PER_SEC=1024       # Telemetry bandwidth limit in KiB per second
export HYPERPROBE_COOLDOWN_SEC=10                # Delay before attempting recovery after suspension

# --- SOURCE LOCATIONS (string) ---
export HYPERPROBE_APP_ROOT=""                    # Prefix to strip from probe source paths

# --- DATA & REDACTION CONTROLS ---
export HYPERPROBE_REDACT_KEYS="password,secret,token,authorization,cookie,key,signature"
export HYPERPROBE_REDACT_VALUES=""               # Comma-separated regex patterns; none by default
export HYPERPROBE_MAX_OBJECT_DEPTH=3             # Maximum object traversal depth
export HYPERPROBE_MAX_ARRAY_LENGTH=3             # Maximum captured array or iterable elements
export HYPERPROBE_MAX_OBJECT_PROPERTIES=50       # Maximum captured fields or map entries
export HYPERPROBE_MAX_STRING_LENGTH=1024         # String truncation limit
export HYPERPROBE_STACK_FRAME_DEPTH=3            # Maximum stack frames per snapshot

# --- OPTIONAL STARTUP & DEBUGGING (unset by default) ---
# export HYPERPROBE_DISABLED=YES                 # Disable the agent at startup
# export DEBUG="hyperprobe*"                    # Enable agent debug logging

# --- OPTIONAL TRACE ID HOOK (strings) ---
# export HYPERPROBE_TRACE_ID_CLASS="com.example.TraceIdHook"
# export HYPERPROBE_TRACE_ID_METHOD="getTraceId" # Default method name

Core settings

GIT_COMMIT, HYPERPROBE_SERVICE_ID, HYPERPROBE_ENVIRONMENT, and HYPERPROBE_BROKER_URL must be nonblank. The agent does not start if GIT_COMMIT is unknown. Java does not read HYPERPROBE_COMMIT_SHA.
HYPERPROBE_BROKER_URL accepts an HTTP(S) URL or a raw gRPC target such as localhost:50051. Do not include a trailing slash or query string. HTTPS enables TLS; HTTP and raw targets use plaintext gRPC.
HYPERPROBE_DISABLED disables startup only when set to YES (case-insensitive). true and 1 do not disable the agent.

Capture and redaction

Use positive integers for numeric limits. Missing or invalid integer values fall back to defaults. HYPERPROBE_REDACT_KEYS and HYPERPROBE_REDACT_VALUES accept comma-separated, case-insensitive regular expressions. Key patterns match field names and redact their values; value patterns redact matching portions of strings. A nonempty key list replaces the default list, so include the defaults when adding custom patterns. An empty value does not clear the default key rules. These capture and redaction settings provide startup defaults. Broker configuration can update them, and individual snapshot probes can override numeric capture limits.

Java does not expose environment variables for queue size, RPC timeout, event-loop lag, or pause budgets. Options such as HYPERPROBE_MAX_QUEUE_SIZE and HYPERPROBE_MAX_LAG_MS from other SDKs do not apply.

Logging and trace ID hooks

DEBUG accepts comma- or space-separated namespaces, such as hyperprobe*. It enables debug output without changing normal info, warning, or error logging. For custom trace IDs, set HYPERPROBE_TRACE_ID_CLASS to a class with a public static, zero-argument method. HYPERPROBE_TRACE_ID_METHOD defaults to getTraceId. Without a custom class, the agent looks for com.hyperprobe.hook.TraceIdHook.getTraceId(). You can also use -Dhyperprobe.traceid.class=... and -Dhyperprobe.traceid.method=...; these JVM properties take precedence over the corresponding environment variables.

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 SDK Setup Guide

Technical Prerequisites

Downloading the Agent

Installation & Deployment

Deployment Templates

🛠️ Build-Tool & Framework Setup

Configuration and environment variables

Core settings

Capture and redaction

Logging and trace ID hooks

Memory Safety Shields

​Technical Prerequisites

​Downloading the Agent

​Installation & Deployment

​Deployment Templates

​🛠️ Build-Tool & Framework Setup

​Configuration and environment variables

​Core settings

​Capture and redaction

​Logging and trace ID hooks

​Memory Safety Shields

Technical Prerequisites

Downloading the Agent

Installation & Deployment

Deployment Templates

🛠️ Build-Tool & Framework Setup

Configuration and environment variables

Core settings

Capture and redaction

Logging and trace ID hooks

Memory Safety Shields