Connect Java to Bugsink

When a Java application fails, Bugsink gives you the exception, stack trace, and context you need to investigate it.

This guide covers the initial setup, other ways to capture failures, and the useful context you can attach to them. You’ll start by connecting an application and triggering a deliberate error to confirm that it reaches Bugsink.

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 Maven project. Bugsink accepts the Sentry event protocol, so the SDK can send events directly to your Bugsink project:

<dependency>
  <groupId>io.sentry</groupId>
  <artifactId>sentry</artifactId>
  <version>${sentry.version}</version>
</dependency>

Configure your DSN

Initialize the SDK early in your application’s startup. Reading the DSN from the environment keeps it out of source control. The in-app package tells Bugsink which stack frames belong to your code rather than the JDK or a library:

Sentry.init(options -> {
    options.setDsn(System.getenv("SENTRY_DSN"));
    options.addInAppInclude("com.example.inventory");
});

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:

throw new IllegalStateException("Bugsink setup check");

Run that code path once. The exception still follows the command’s normal failure path; the SDK’s uncaught-exception handler reports it before the process exits.

See the error in Bugsink

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

Bugsink preview

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

Capture other kinds of errors

Uncaught exceptions arrive automatically. You can also report exceptions your code catches, severe log records, and exceptional conditions that do not have an exception.

Handled exceptions

Capturing a handled exception sends it to Bugsink without changing how your code recovers. Call captureException() inside a catch block when you still want the original stack trace and failure message after the application has decided to continue:

try {
    inventory.reserve(order);
} catch (ProductNotFound exception) {
    Sentry.captureException(exception);
}

The exception remains handled by the application and appears as an issue in Bugsink.

Bugsink preview: handled exception
Bugsink preview

Java Util Logging

Java Util Logging records can become Bugsink events through sentry-jul. Add that module and slf4j-api, which the current adapter uses for MDC values, then configure its handler. Informational records become breadcrumbs; SEVERE records become events:

<dependency>
  <groupId>io.sentry</groupId>
  <artifactId>sentry-jul</artifactId>
  <version>${sentry.version}</version>
</dependency>
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-api</artifactId>
  <version>${slf4j.version}</version>
</dependency>

Configure the standard logging system to pass records to both the console and the Sentry handler:

handlers=java.util.logging.ConsoleHandler,io.sentry.jul.SentryHandler
.level=INFO
java.util.logging.ConsoleHandler.level=INFO
io.sentry.jul.SentryHandler.level=INFO
io.sentry.jul.SentryHandler.minimumBreadcrumbLevel=INFO
io.sentry.jul.SentryHandler.minimumEventLevel=SEVERE

Start the JVM with -Djava.util.logging.config.file=/path/to/logging.properties. Normal logger calls then remain the only code needed at the failure site:

JUL_LOGGER.info("Loading inventory snapshot");
try {
    inventory.reserve(order);
} catch (ProductNotFound exception) {
    JUL_LOGGER.log(Level.SEVERE, "Inventory reconciliation failed", exception);
}

The severe record becomes an event with its logger name and attached exception. The earlier informational record is available as a breadcrumb on that event.

Bugsink preview: JUL record
Bugsink preview

Logback

Logback records can become Bugsink events without replacing the SLF4J calls your application already makes. Add sentry-logback and logback-classic; informational records become breadcrumbs, while error records become events with their logger name and attached exception:

<dependency>
  <groupId>io.sentry</groupId>
  <artifactId>sentry-logback</artifactId>
  <version>${sentry.version}</version>
</dependency>
<dependency>
  <groupId>ch.qos.logback</groupId>
  <artifactId>logback-classic</artifactId>
  <version>${logback.version}</version>
</dependency>

Configure both the normal console appender and the Bugsink appender. The SDK initialized during startup supplies the DSN, so it does not need to be repeated in this file:

<configuration>
  <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>%level %logger - %msg%n</pattern>
    </encoder>
  </appender>
  <appender name="BUGSINK" class="io.sentry.logback.SentryAppender">
    <minimumBreadcrumbLevel>INFO</minimumBreadcrumbLevel>
    <minimumEventLevel>ERROR</minimumEventLevel>
  </appender>
  <root level="INFO">
    <appender-ref ref="CONSOLE"/>
    <appender-ref ref="BUGSINK"/>
  </root>
</configuration>

Normal SLF4J calls then remain the only code needed at the failure site:

LOGBACK_LOGGER.info("Loading fulfillment queue");
try {
    inventory.reserve(order);
} catch (ProductNotFound exception) {
    LOGBACK_LOGGER.error("Inventory fulfillment failed", exception);
}

The error record becomes the Bugsink event, and the preceding informational record is attached to it as a breadcrumb.

Bugsink preview: Logback record
Bugsink preview

Log4j 2

Log4j 2 records can become Bugsink events through the logger calls already in your application. Add sentry-log4j2 alongside the Log4j API and Core modules; informational records become breadcrumbs, while error records become events with their logger name and attached exception:

<dependency>
  <groupId>io.sentry</groupId>
  <artifactId>sentry-log4j2</artifactId>
  <version>${sentry.version}</version>
</dependency>
<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-api</artifactId>
  <version>${log4j2.version}</version>
</dependency>
<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-core</artifactId>
  <version>${log4j2.version}</version>
</dependency>

Add the Bugsink appender to your normal Log4j 2 configuration. It reads the same SENTRY_DSN environment variable, so the DSN does not need to be repeated here. These thresholds keep INFO records as breadcrumbs and send ERROR records as events:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
  <Appenders>
    <Console name="CONSOLE" target="SYSTEM_ERR">
      <PatternLayout pattern="%level %logger - %msg%n"/>
    </Console>
    <Sentry name="BUGSINK"
            minimumBreadcrumbLevel="INFO"
            minimumEventLevel="ERROR"/>
  </Appenders>
  <Loggers>
    <Root level="INFO">
      <AppenderRef ref="CONSOLE"/>
      <AppenderRef ref="BUGSINK"/>
    </Root>
  </Loggers>
</Configuration>

Your failure path remains ordinary Log4j 2 code:

LOG4J2_LOGGER.info("Loading shipment manifest");
try {
    inventory.reserve(order);
} catch (ProductNotFound exception) {
    LOG4J2_LOGGER.error("Inventory shipment failed", exception);
}

The error record becomes the Bugsink event. The earlier informational record is attached to it as a breadcrumb.

Bugsink preview: Log4j 2 record
Bugsink preview

Messages without exceptions

A message creates a Bugsink event without an exception. Use captureMessage() for a condition such as an unresponsive queue or failed defensive check, and pass the text and severity Bugsink should show. Prefer an exception or normal logging when either represents the failure more naturally:

Sentry.captureMessage("Order queue is not responding", SentryLevel.ERROR);

Bugsink preview: captured message
Bugsink preview

Short-lived commands

Closing the SDK waits briefly for queued events before a short-lived process exits. Put Sentry.close() in a finally block around batch or command-line work. Long-running services should leave the SDK open and do not need to flush after every event:

Sentry.close();

Add useful context

An exception tells you what failed; context helps explain why. Context added to the current scope is attached to events captured inside that scope.

Tags

Tags make events searchable by short key/value pairs. Bugsink already has standard fields such as environment and release; use setTag() for your own component, region, plan, or feature flag. This call adds component:inventory to the event captured in the temporary scope:

scope.setTag("component", "inventory");

Bugsink preview: component tag
Bugsink preview

Structured context

Structured context adds a named group of details to an event. Use it for values you want to inspect but not search, such as the order or job being processed. setContexts("order", ...) creates an Order section containing the identifier, SKU, and quantity. A LinkedHashMap keeps those fields in a predictable order:

LinkedHashMap<String, Object> orderContext = new LinkedHashMap<>();
orderContext.put("id", order.id());
orderContext.put("sku", order.sku());
orderContext.put("quantity", order.quantity());
scope.setContexts("order", orderContext);

Bugsink preview: structured context
Bugsink preview

Breadcrumbs record what happened before an error. Add one for a step the SDK cannot know about, such as reserving inventory or retrying an external call. The breadcrumb creates no event on its own; the next captured event includes its category, message, and data:

Breadcrumb breadcrumb = Breadcrumb.info("Starting inventory reservation");
breadcrumb.setCategory("order");
breadcrumb.setData("order_id", order.id());
scope.addBreadcrumb(breadcrumb);

Bugsink preview: breadcrumb
Bugsink preview

Limitations

For a normal JVM build, the stack trace already gives Bugsink the class, method, filename, and line number shown above. Bugsink does not currently add the surrounding Java source lines from an uploaded source bundle.

The Gradle plugin can upload a source bundle, and Bugsink accepts and stores it, but Bugsink does not yet apply that bundle to the event. The Kotlin/JVM guide shows the Gradle setup and the build metadata Bugsink stores. ProGuard and R8 mapping files are not applied either, so names from an obfuscated build remain obfuscated.

Applying uploaded source is tracked in Java and Gradle source uploads #64 and the broader source context tracker #205.

JVM frameworks and languages

JVM integrations capture failures through their normal application lifecycle and preserve the relevant request, language, and build context.