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><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"); });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/1export 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");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.
IllegalStateException
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); }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
ProductNotFound
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><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=SEVEREhandlers=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); }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.
error inventory Inventory reconciliation failedBugsink preview: JUL record
Log Entry
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><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><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); }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.
error inventory.fulfillment Inventory fulfillment failed Inventory fulfillment failedBugsink preview: Logback record
Log Entry
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><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><?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); }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.
error inventory.shipping Inventory shipment failed Inventory shipment failedBugsink preview: Log4j 2 record
Log Entry
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);Sentry.captureMessage("Order queue is not responding", SentryLevel.ERROR);
error Order queue is not respondingBugsink preview: captured message
Log Entry
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();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");scope.setTag("component", "inventory");
inventoryBugsink preview: component tag
Tags
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);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);
order-3002 java-handled 1Bugsink preview: structured context
Contexts
ORDER
Breadcrumbs
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);Breadcrumb breadcrumb = Breadcrumb.info("Starting inventory reservation"); breadcrumb.setCategory("order"); breadcrumb.setData("order_id", order.id()); scope.addBreadcrumb(breadcrumb);
Bugsink preview: breadcrumb
order
Starting inventory reservation
event time
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.
