Java error tracking SDK for JVM and Kotlin

RetraceKit ships a Java SDK for error tracking on JVM services written in Java or Kotlin. You add cloud.retracekit:sdk, call RetraceKit.init, and exceptions become events in your project: issues, automatic incidents, AI summaries, and alerts.

Gradle (Kotlin DSL):

dependencies {
    implementation("cloud.retracekit:sdk:0.1.1")
}

Maven:

<dependency>
  <groupId>cloud.retracekit</groupId>
  <artifactId>sdk</artifactId>
  <version>0.1.1</version>
</dependency>

Coordinates: cloud.retracekit:sdk. Source: github.com/RetraceKit/sdk-java. Full setup: Java environment docs. Related reading on the blog.

From exception to event

The triage path is short:

1. An exception fires in your process (uncaught on a thread, or a manual captureException call).
2. The SDK builds an event: message, stack, release, environment, tags, breadcrumbs, session id, optional user.
3. RetraceKit fingerprints matching crashes into one issue.
4. When related issues share a route, release, or session, RetraceKit opens an incident so you triage one outage instead of a pile of tickets.

You read the AI brief, open the linked issues, and ship a fix against the release that lit up.

What you get

• Auto-capture for uncaught exceptions via Thread.setDefaultUncaughtExceptionHandler after init (existing handlers stay wrapped)
• Manual reporting with captureException
• Breadcrumbs, user context, and tags
• Java and Kotlin call sites on the same artifact
• Runtime dependency: kotlin-stdlib only
• Java 17+ bytecode
• Client-side dedup that suppresses identical crashes for 30 seconds so a tight loop does not flood ingest
• A session ping on init so the process shows up in session-aware views

Captured exceptions land as events. You keep plans you already know: Free at 100,000 stored events, Plus at $5.99/month, Pro at $14.99/month.

Quick start

Java:

import com.retracekit.sdk.Config;
import com.retracekit.sdk.RetraceKit;

RetraceKit.init(
    Config.builder()
        .apiKey(System.getenv("RETRACE_KIT_API_KEY"))
        .build()
);

Kotlin:

import com.retracekit.sdk.Config
import com.retracekit.sdk.RetraceKit

RetraceKit.init(
    Config(
        apiKey = System.getenv("RETRACE_KIT_API_KEY")!!,
    ),
)

After init, uncaught errors on JVM threads become events automatically. For handled paths, call captureException, attach setUser / setTag, and add breadcrumbs before the failure. apiKey is enough. Optional release should come from the JAR Implementation-Version.

Init options

Option	Env var	Notes
apiKey	RETRACE_KIT_API_KEY	Required. Blank key disables sending and logs a warning.
environment	RETRACE_KIT_ENVIRONMENT	Attached to every event (for example production).
enabled	-	Set false to keep hooks quiet in local runs.

The SDK sets tag runtime=java and a userAgent like Java 21.0.2 so you can filter backend traffic in the project inbox.

Dedup and sessions

A noisy worker that throws the same stack in a loop would burn storage if every throw became a new row. The Java SDK computes a dedup key from the exception class, message, and last stack frame, then drops duplicates inside a 30-second window. After the window, the same crash can report again.

On init, the SDK allocates a sessionId and sends a session ping. Later events reuse that id, which feeds session correlation and incident rules that group by session.

Java and Kotlin

One artifact covers both languages. Kotlin uses the Config constructor. Java uses Config.builder(). Methods on RetraceKit are @JvmStatic, so you do not need a companion-object qualifier from Java.

There is no Spring Boot starter or servlet filter in this package. Uncaught JVM exceptions still report after init. Request-scoped crashes inside try/catch need captureException.

Manual capture example

import com.retracekit.sdk.BreadcrumbType
import com.retracekit.sdk.Config
import com.retracekit.sdk.RetraceKit

val release = App::class.java.getPackage()?.implementationVersion

RetraceKit.init(
    Config(
        apiKey = System.getenv("RETRACE_KIT_API_KEY")!!,
        release = release,
    ),
)

RetraceKit.setUser("user_123")
RetraceKit.setTag("plan", "pro")
RetraceKit.addBreadcrumb(
    type = BreadcrumbType.COMMON,
    name = "checkout",
    value = "started",
)

try {
    checkout()
} catch (error: Throwable) {
    RetraceKit.captureException(error, mapOf("url" to request.requestURI))
}

Breadcrumbs and tags travel with the event so the issue page shows what happened before the throw. See breadcrumbs and current user for how those fields show up in the app.

Verify the first event

1. Set RETRACE_KIT_API_KEY from project settings in the app.
2. Call RetraceKit.init at process start (before you serve traffic).
3. Throw once: throw new RuntimeException("retrace-kit smoke test"), or catch and captureException.
4. Open Issues in the app. You should see an event with runtime=java and a Java userAgent.

If nothing arrives, check that the key is non-blank and enabled is not false. Pass url on captureException so the issue page has a route.

Why this matters for small teams

Backend crashes should land in the same triage flow as everything else you already track. One RetraceKit project turns JVM exceptions into events, groups them into issues, and opens an incident when a release lights up related fingerprints. You keep Free at 100,000 stored events, or paid plans under $15/month with longer retention.

Links

• Java docs
• Java SDK repository
• Incidents
• Plans
• Blog

FAQ

Which Java versions does RetraceKit support?

Java 17 and newer. The SDK is Kotlin source compiled to Java 17 bytecode, so you call it from Java or Kotlin.

Does the Java SDK work from Kotlin?

Yes. RetraceKit.init takes a Config data class from Kotlin, or Config.builder() from Java. captureException, setUser, setTag, and addBreadcrumb are @JvmStatic on the RetraceKit object.

What is the only runtime dependency?

kotlin-stdlib. There is no Spring, servlet, or HTTP-client extra. The SDK uses java.net.http for ingest.

What happens to JVM exceptions in RetraceKit?

Exceptions become events. Identical crashes group into issues. Related issues that share a route, release, or session open an automatic incident. AI summaries and third-party alerts work on those events.

What does auto-capture cover on the JVM?

After init, RetraceKit wraps Thread.setDefaultUncaughtExceptionHandler and still calls any handler that was already installed. Handled try/catch paths need captureException. There is no Spring or servlet filter in this package.