> ## 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 Agent 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 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)](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. To adhere to twelve-factor principles and prevent configuration leakage, the Java agent reads setup parameters **exclusively from environment variables**.

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

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

***

## 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=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:

    ```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: "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"]
    ```
  </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", "billing-service")
      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", "billing-service"
      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>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>
    ```
  </Tab>
</Tabs>

***

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