https://github.com/backtrace-labs/backtrace-java
Java support for Backtrace
https://github.com/backtrace-labs/backtrace-java
Last synced: 9 months ago
JSON representation
Java support for Backtrace
- Host: GitHub
- URL: https://github.com/backtrace-labs/backtrace-java
- Owner: backtrace-labs
- License: mit
- Created: 2019-10-21T15:28:19.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-07-05T20:26:26.000Z (over 2 years ago)
- Last Synced: 2025-04-22T23:14:38.080Z (9 months ago)
- Language: Java
- Homepage:
- Size: 324 KB
- Stars: 6
- Watchers: 11
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# This library is currently in early access
We are working closely with users for their initial rollouts of backtrace-java. Please reach out to us via your account rep or support@backtrace.io for more details.
# Backtrace Java support
[Backtrace](http://backtrace.io/)'s integration with Java applications which allows customers to capture and report handled and unhandled java exceptions to their Backtrace instance, instantly offering the ability to prioritize and debug software errors.
[](https://github.com/backtrace-labs/backtrace-java/actions)
# Features Summary
* Light-weight Java client library that quickly submits exceptions to your Backtrace dashboard. Can include callstack, system metadata, custom metadata and file attachments if needed.
* Supports offline database for error report storage and re-submission in case of network outage.
* Fully customizable and extendable event handlers and base classes for custom implementations.
# Installation via Gradle or Maven
* Gradle
```
dependencies {
implementation 'com.github.backtrace-labs.backtrace-java:backtrace-java:'
}
```
* Maven
```
com.github.backtrace-labs.backtrace-java
backtrace-java
```
# Using Backtrace library
## Initialize a new BacktraceClient
First create a `BacktraceConfig` instance with your `Backtrace endpoint URL`. This endpoint URL will either be through a central https://submit.backtrace.io server on standard port 80/443, or directly to your Backtrace instance through a listener on port 6097/6098 (e.g. https://xxx.sp.backtrace.io:6098). Either integration will require a submission token to be included in the endpoint
Option 1 - https://submit.backtrace.io URL format option for creating a BacktraceConfig object. Use the URL to which the report is to be sent, pass URL string as parameter to BacktraceConfig constructor:
```java
BacktraceConfig config = new BacktraceConfig("https://submit.backtrace.io/{yourInstance}/{token}/json");
BacktraceClient backtraceClient = new BacktraceClient(config);
```
Option 2 - https://.sp,backtrace.io:6098 format for creating BacktraceCredentials object. Pass in both your instance submission URL and token as parameters of the BacktraceConfig constructor:
Java
```java
BacktraceConfig config = new BacktraceConfig("https://.sp.backtrace.io:6098/", "");
BacktraceClient backtraceClient = new BacktraceClient(config);
```
## Setting application name and version
In order to easily distinguish which errors belong to which application it is recommended to set the application version and its name. This data will be sent as attributes to the Backtrace console.
```java
backtraceClient.setApplicationName("Backtrace Demo");
backtraceClient.setApplicationVersion("1.0.0");
```
###
By default, BacktraceClient stores error reports to the local disk using BacktraceDatabase. Each report is serialized and stored in separate file in database directory.
### Disabling database
If you don't want to use local file database, you can disable that.
```java
backtraceConfig.disableDatabase();
```
If the database is disabled, you can enable it.
```java
backtraceConfig.enableDatabase();
```
### Max database size
You can set a maximum database size in bytes, by default size is unlimited. If the database size reaches the limit, the oldest error reports will be deleted.
```java
backtraceConfig.setMaxDatabaseSize(size);
```
### Max record count
If a limit is set, the oldest error reports will be deleted if there will be try to exceed the limit.
```java
backtraceConfig.setMaxRecordCount(numberOfRecords);
```
### Max retry limit
The retry limit specifies the number of times `BacktraceClient` will try to send the error report again if sending will finished with fail.
```java
backtraceConfig.setDatabaseRetryLimit(retryLimit);
```
## Enabling gathering information about all threads
By default library gathering stacktrace and other information only from thread in which caused exception. If you want to change that behavior and gather information about all running threads, execute:
```java
backtraceConfig.setGatherAllThreads(false);
```
## Sending an error report
Method `BacktraceClient.send` will send an error report to the Backtrace endpoint specified. There `send` method is overloaded, see examples below:
### Using `BacktraceReport`
The `BacktraceReport` class represents a single error report. (Optional) You can also submit custom attributes using the `attributes` parameter. You can also pass list of file paths to files which will be send to API in `attachmentPaths` parameter.
```java
try {
// throw exception here
} catch (Exception e) {
BacktraceReport report = new BacktraceReport(e,
new HashMap() {{
put("key", "value");
}}, new ArrayList() {{
add("absoulte_file_path_1");
add("absoulte_file_path_2");
}});
backtraceClient.send(report);
}
```
### Asynchronous `send` support
Method `send` behind the mask use dedicated thread which sending report to server. You can specify the method that should be performed after completion.
```java
client.send(report, new OnServerResponseEvent() {
@Override
public void onEvent(BacktraceResult backtraceResult) {
// process result here
}
});
```
Method `await` of BacktraceClient allows to block current thread until all passed reports will be sent, as a parameter you can optionally set the maximum time you want to wait for an answer.
```java
backtraceClient.await(5, TimeUnit.SECONDS);
```
### Other `BacktraceReport` overloads
`BacktraceClient` can also automatically create `BacktraceReport` given an exception or a custom message using the following overloads of the `BacktraceClient.send` method:
Java
```java
try {
// throw exception here
} catch (Exception exception) {
backtraceClient.send(new BacktraceReport(exception));
// pass exception to send method
backtraceClient.send(exception);
// pass your custom message to send method
backtraceClient.send("message");
}
```
### System Metadata
The following system metadata is associated to a BacktraceReport
- system global environment variables
- number of cpu cores
- OS name and version
- hostname (if possible)
- memory_total - total amount of memory in the Java virtual machine
- memory_max - maximum amount of memory that the Java virtual machine will attempt to use
- memory-free - free memory in the Java Virtual Machine
## Attaching custom event handlers
All events are written in *listener* pattern. `BacktraceClient` allows you to attach your custom event handlers. For example, you can trigger actions before the `send` method:
```java
backtraceClient.setBeforeSendEvent(new BeforeSendEvent() {
@Override
public BacktraceData onEvent(BacktraceData data) {
// another code
return data;
}
});
```
`BacktraceClient` currently supports the following events:
- `BeforeSend`
- `RequestHandler`
## Reporting unhandled application exceptions
`BacktraceClient` supports reporting of unhandled application exceptions not captured by your try-catch blocks. To enable reporting of unhandled exceptions run the code below.
```java
backtraceClient.enableUncaughtExceptionsHandler();
```
## BacktraceReport
**`BacktraceReport`** is a class that describe a single error report. Contains attributes, message, exception stack and paths to attachments.
## BacktraceClient
`BacktraceClient` is a class that allows you to instantiate a client instance that interacts with Backtrace. This class sets up connection to the Backtrace endpoint and manages error reporting behavior. It also prepares error report, gather device attributes and add to queue from which special thread gets report and sends to Backtrace. This class also allows to enable `UncaughtExceptionsHandler` or set custom events.
if you want to safely close all resources used by the this library, execute `close` method. This method will do this after processing last message in queue:
```java
backtraceClient.close()
```
## BacktraceData
**`BacktraceData`** is a serializable class that holds the data to create a diagnostic JSON to be sent to the Backtrace endpoint . You can add additional pre-processors for `BacktraceData` by attaching an event handler to the `BacktraceClient.setBeforeSendEvent(event)` event. `BacktraceData` require `BacktraceReport` and `BacktraceClient` client attributes.
## BacktraceResult
**`BacktraceResult`** is a class that holds response and result from a `send` method call. The class contains a `status` property that indicates whether the call was completed (`OK`), the call returned with an error (`ServerError`). Additionally, the class has a `message` property that contains details about the status.