Connect Kotlin/JVM to Bugsink

Kotlin applications running on the JVM use the Java SDK. Bugsink shows their Kotlin exception, stack trace, and application context.

This guide adds the SDK to a Gradle application and triggers a deliberate error. It then covers handled exceptions, Kotlin context, and the current state of JVM source uploads.

To follow along, create a Bugsink project and copy its DSN. The quickstart guide shows where to find it.

Install the SDK

Add the open-source Sentry Java SDK to your Kotlin/JVM dependencies. Bugsink accepts the Sentry event protocol, so the SDK can send events directly to your Bugsink project:

dependencies {
    implementation("io.sentry:sentry:8.65.0")
}

Configure your DSN

Initialize the SDK early in your application’s startup. The DSN comes from the environment, while the package prefix tells Bugsink which JVM frames belong to your Kotlin application. A release identifies the build that produced them:

Sentry.init { options ->
    options.dsn = dsn
    options.addInAppInclude("com.example.inventory")
    options.release = "inventory-kotlin@1.0.0"
}

Set SENTRY_DSN to the DSN shown by your Bugsink project when you run the application:

export SENTRY_DSN=https://key@bugsink.example/1

Send a test error

Temporarily add an exception to a code path you can run:

error("Bugsink setup check")

Build and run that path once. The exception still terminates the command normally; the SDK reports it before the JVM exits:

./gradlew --no-daemon installDist
build/install/bugsink-kotlin-inventory/bin/bugsink-kotlin-inventory setup

See the error in Bugsink

Open your Bugsink project. The new IllegalStateException issue contains the Kotlin stack trace and identifies the application line that raised it.

Bugsink preview

That’s it: your Kotlin/JVM application is connected. Remove the deliberate exception. Bugsink will capture future uncaught exceptions without reporting calls in your application code.

Handled exceptions

Capturing a handled exception sends it to Bugsink while a batch, consumer, or request continues. Call captureException() inside the catch branch after your application has decided how to recover:

Sentry.captureException(exception)

The example batch rejects one order and still reserves the next one. Bugsink keeps the original failure frame.

Bugsink preview: handled exception
Bugsink preview

Kotlin context

Tags, structured context, and breadcrumbs explain which work failed and what happened first. This scoped block adds a searchable component tag, the checkout values to inspect, and the rejected inventory action before capturing the exception:

scope.setTag("component", "inventory")
scope.setContexts(
    "checkout",
    linkedMapOf("order_id" to order.id, "sku" to order.sku),
)
scope.addBreadcrumb(
    Breadcrumb.info("Rejected an inventory order").apply {
        category = "inventory"
        setData("sku", order.sku)
    },
)

Each part is visible in its corresponding Bugsink view.

Bugsink preview: component tag
Bugsink preview

Bugsink preview: checkout context
Bugsink preview

Bugsink preview: breadcrumb
Bugsink preview

JVM source uploads

The Sentry Gradle plugin can create a JVM source bundle and dependency report. Its normal build integration works with Bugsink’s compatible debug-file upload API, but source context has an important limitation described below.

Configure the plugin

Apply the plugin next to Kotlin’s JVM plugin:

plugins {
    application
    kotlin("jvm") version "2.4.21"
    id("io.sentry.jvm.gradle") version "6.27.0"
}

Configure source and dependency collection. autoInstallation remains off because the SDK dependency is already explicit; the organization value is only a compatibility placeholder because Bugsink projects are not nested in organizations:

sentry {
    includeSourceContext.set(true)
    includeDependenciesReport.set(true)
    autoUploadSourceContext.set(providers.environmentVariable("SENTRY_AUTH_TOKEN").isPresent)
    org.set("bugsink")
    projectName.set(providers.environmentVariable("BUGSINK_PROJECT_SLUG").orElse("inventory-kotlin"))
    authToken.set(providers.environmentVariable("SENTRY_AUTH_TOKEN"))
    url.set(providers.environmentVariable("BUGSINK_URL"))
    telemetry.set(false)

    autoInstallation {
        enabled.set(false)
    }
}

Upload the bundle

Create a Bugsink API token scoped to the application project with only the debug-files:upload capability. The token is a build credential; keep it out of the running application’s environment.

Set the Bugsink URL, project slug, and token before the normal Gradle assembly:

export BUGSINK_URL=https://bugsink.example
export BUGSINK_PROJECT_SLUG=inventory-service
export SENTRY_AUTH_TOKEN=your-project-token
./gradlew --no-daemon assemble

Without SENTRY_AUTH_TOKEN, the application still builds and the plugin skips the upload.

Current limitation

Bugsink accepts the JVM bundle and stores its ID on the event. It also stores the Kotlin and SDK dependency versions. Bugsink does not yet apply the bundle to JVM frames, so the Kotlin filename and line number arrive without the source line or surrounding context.

Bugsink preview: JVM source context limitation
Bugsink preview

For messages, Java logging integrations, and more context options, continue with the Java guide.