> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperprobe.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Java SDK Setup Guide

> Configure and attach the standard Java Instrumentation agent to your running JVM applications with zero code changes.

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)](https://central.sonatype.com/artifact/co.hyperprobe/hyperprobe-agent/versions).

***

## 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](https://central.sonatype.com/artifact/co.hyperprobe/hyperprobe-agent/versions)):

```bash curl theme={null}
curl -L -o hyperprobe-agent.jar "https://repo1.maven.org/maven2/co/hyperprobe/hyperprobe-agent/<LATEST_VERSION>/hyperprobe-agent-<LATEST_VERSION>.jar"
```

```bash wget theme={null}
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.

```bash theme={null}
# 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
```

<Note>
  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](#configuration-and-environment-variables).
</Note>

***

## Deployment Templates

<Tabs>
  <Tab title="Docker Multi-Stage Build">
    It is best practice to download the agent jar during build-time and bake the Git commit into the final image:

    ```dockerfile Dockerfile theme={null}
    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:

    ```bash theme={null}
    docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) -t app:latest .
    ```
  </Tab>

  <Tab title="Kubernetes Manifest">
    Expose your environment parameters inside your deployment's spec definition:

    ```yaml deployment.yaml theme={null}
    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"]
    ```
  </Tab>
</Tabs>

***

## 🛠️ Build-Tool & Framework Setup

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

<Tabs>
  <Tab title="Gradle (Kotlin DSL)">
    Add the agent args to your standard Spring Boot run tasks inside `build.gradle.kts`:

    ```kotlin build.gradle.kts theme={null}
    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")
    }
    ```
  </Tab>

  <Tab title="Gradle (Groovy DSL)">
    ```groovy build.gradle theme={null}
    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"
    }
    ```
  </Tab>

  <Tab title="Maven (pom.xml)">
    ```xml pom.xml theme={null}
    <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>
    ```
  </Tab>
</Tabs>

***

## 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.

```bash theme={null}
# --- 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.

<Note>
  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.
</Note>

### 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.