Kotlin SDK Setup Guide

HyperProbe supports Kotlin/JVM applications through the same agent used for Java. Attach the agent at startup to capture variables, stack frames, metrics, and logs without adding an initializer or annotations.

Technical prerequisites

Runtime: Kotlin/JVM on Java 17 or later. This guide does not apply to Kotlin/JS or Kotlin/Native.
Metadata: The Git commit SHA used to build your deployed application.
Debug information: Preserve source filenames, line numbers, and local variable metadata in your compiled classes so probes can resolve .kt source locations and capture locals.

Installation

Download the agent JAR. Replace <LATEST_VERSION> with a version from Maven Central:

curl -L -o hyperprobe-agent.jar "https://repo1.maven.org/maven2/co/hyperprobe/hyperprobe-agent/<LATEST_VERSION>/hyperprobe-agent-<LATEST_VERSION>.jar"

You do not need a separate Kotlin SDK dependency. Adding the JAR as an application dependency alone does not activate the agent; you must pass -javaagent to the application JVM.

Initialization walkthrough

Set environment variables

Export these variables before starting your application. Replace the service ID with the UUID from your HyperProbe dashboard:

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

Use git rev-parse HEAD for local runs. In CI/CD, set GIT_COMMIT to the commit used to build the deployed artifact. The agent does not start if it is missing or set to unknown.

Attach the agent

Choose how you start your application. These examples assume the downloaded JAR is in your project root and the environment variables above are set.

Executable JAR
Spring Boot (Gradle)
Spring Boot (Maven)

java -javaagent:./hyperprobe-agent.jar -jar build/libs/app.jar

Replace build/libs/app.jar with your executable application JAR.

Add the agent to your bootRun task:

build.gradle.kts

tasks.named<org.springframework.boot.gradle.tasks.run.BootRun>("bootRun") {
    jvmArgs("-javaagent:${rootDir}/hyperprobe-agent.jar")
}

./gradlew bootRun

mvn spring-boot:run \
  -Dspring-boot.run.jvmArguments="-javaagent:$(pwd)/hyperprobe-agent.jar"

Keep your existing Kotlin main function unchanged. The agent starts before your application.

Docker deployment

Copy the downloaded agent and your built application into the image. Adjust the application JAR path to match your build output:

Dockerfile

FROM eclipse-temurin:21-jre
WORKDIR /app

ARG GIT_COMMIT
ENV GIT_COMMIT=${GIT_COMMIT}

COPY hyperprobe-agent.jar /app/hyperprobe-agent.jar
COPY build/libs/app.jar /app/app.jar

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

Build and run locally with the environment variables from the initialization step:

docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) -t app:latest .
docker run --rm \
  -e HYPERPROBE_SERVICE_ID \
  -e HYPERPROBE_ENVIRONMENT \
  -e HYPERPROBE_BROKER_URL \
  app:latest

Configuration and environment variables

Kotlin uses the same environment variables and defaults as Java. See the complete environment variable reference for performance limits, capture depth, redaction, logging, and trace ID hooks. To disable the agent at startup, set HYPERPROBE_DISABLED=YES.

Get Started

AI-Native Debugging

VS Code Extension

SDK Integration

Probe Types

Guides

Troubleshooting

Self-Hosting

Kotlin SDK Setup Guide

Technical prerequisites

Installation

Initialization walkthrough

Docker deployment

Configuration and environment variables

​Technical prerequisites

​Installation

​Initialization walkthrough

​Docker deployment

​Configuration and environment variables

Technical prerequisites

Installation

Initialization walkthrough

Docker deployment

Configuration and environment variables