Java

Rollbar SDK for Java and Android

Quick Start

For the most basic Java applications use this to install rollbar-java:

compile('com.rollbar:rollbar-java:1.+')

If you require direct access to the underlying API objects include rollbar-api as a dependency. For Android include rollbar-android. For web projects include rollbar-web.

To configure rollbar-java and send an error and a message:

Config config = ConfigBuilder.withAccessToken("<post_server_item_access_token>")
        .environment("production")
        .codeVersion("1.0.0")
        .build();
Rollbar rollbar = new Rollbar(config);
rollbar.error(exception);
rollbar.info("This is an info message");

These two items should appear in your project's dashboard within a few seconds.

The docs linked below will help you get Rollbar up and running quickly in various platforms and toolchains.

Maven information

Gradle information

Web quick start

Android quick start

Spring MVC quick start

Log4j2 quick start

Logback quick start

Scala quick start

Kotlin quick start

ProGuard Deobfuscation

If you use ProGuard to obfuscate your code in production, reported stack traces will not be very useful in most cases.

Rollbar provides a way for you to upload the mapping.txt file generated in the obfuscation process so that stack traces can be deobfuscated as they are reported.

Here is an example cURL command to upload a mapping.txt file:

curl 'https://api.rollbar.com/api/1/proguard' \
  -F access_token=POST_SERVER_ITEM_ACCESS_TOKEN \
  -F version=0.0.10 \
  -F mapping=@path/to/mapping.txt

Where version matches the android:versionName in your app's AndroidManifest.xml, corresponding to the version the mapping.txt was generated for.

After uploading, any future reported exceptions for the specified version will automatically be deobfuscated using the mapping file.

By default, file names and line numbers are removed by ProGuard. To preserve this information to make debugging easier, add the following to your proguard-project.txt:

-keepattributes SourceFile,LineNumberTable

Usage

There are currently four libraries in this repository:

  • rollbar-api
  • rollbar-java
  • rollbar-web
  • rollbar-android
  • rollbar-log4j2
  • rollbar-logback

rollbar-api is a set of data objects representing structures that make up the payload the backend API understands.

rollbar-java has the core functionality for taking input from your code and transmitting it to our API. rollbar-java depends on rollbar-api and provides many points of customizing its behavior.

rollbar-web is a higher level abstraction built on rollbar-java which intended to be integrated into web servers based on the Servlet API.

rollbar-android is a library for use in an Android environment built on rollbar-java.

The example directory contains examples using rollbar-java directly as well as using rollbar-web and rollbar-android.

For actual usage, the easiest way to get started is by looking at the examples:

How payloads are sent

The actual notifier configuration builds a notifier that uses a BufferedSender to send the items to Rollbar. That sender is built using an unbound memory queue and a scheduled thread to send the events from the queue. The queue as well as the frequency of the scheduled thread can be customized when building the buffered sender and it can be replaced by passing a custom configuration when creating the notifier or initializing it.

How to build it

To build the notifier there are some system environment variables that are needed.

  • ANDROID_HOME. Pointing to the android sdk.
  • JAVA_HOME. Pointing to the java8 sdk.
  • JDK7_HOME. Pointing to the java7 sdk.
./gradlew clean build

Upgrading from Previous Versions

Please see Upgrading from v0.5.4 or earlier to v1.0.0+.

Managing Sensitive Data

GDPR & HIPAA

If you are required to comply with GDPR or HIPAA, we have a few recommendations for how to manage the sensitive data you may be sending to Rollbar. We recommend setting up person tracking, customizing your data retention period (more info on this here), anonymizing or not capturing IP addresses for rollbar-web, and removing sensitive data before sending Rollbar items. For HIPAA compliance, we recommend transforming the payload before sending Rollbar items, as sometimes sensitive data may be found in stack traces.

For information on setting up person tracking, please see here. You can simply send only the person.id and no other identifying information, such as an email address. If you have already sent Rollbar sensitive person data and wish to delete it, please see our documentation on deleting person data here.

You may also configure the captureIp setting in your config to either not capture IP addresses (by setting captureIp to none) or have the SDK do a semi-anonymization on the captured IP address by masking out the least significant bits (by setting captureIp to anonymize). Please note that capturing IP addresses is only possible when using rollbar-web.

Config config = ConfigBuilder.withAccessToken("<access_token>"))
       .environment("development")
       .codeVersion("1.0.0")
       .request(new RequestProvider.Builder().captureIp("anonymize").build())
       .build();

Scrubbing Items

If you need to scrub certain data in the payload before sending it to Rollbar, the best way to do so is via a Transformer function. Please see transforming the payload below.

Transforming the Payload

If you would like to change some of the data in the payload before sending an item to Rollbar, you may do so via a Transformer function.

// For example, to remove the framework:
public class RemoveFrameworkTransformer implements Transformer {

  @Override
  public Data transform(Data data) {
    return new Data.Builder(data)
        .framework(null)
        .build();
  }
}

Config config = ConfigBuilder.withAccessToken("<access_token>"))
        .environment("development")
        .codeVersion("1.0.0")
        .transformer(new RemoveFrameworkTransformer())
        .build();

Ignoring Items

If you would like to have the client ignore an item and not send it to Rollbar, you can use a Transformer function. Please see transforming the payload above. Additionally, you can use a Filter to check the payload and decide if an item should be sent or not.

// Doesn't send items with 'debug' level
public class FilterDebugItems implements Filter {

  @Override
  public boolean preProcess(Level level, Throwable error, Map<String, Object> custom,
      String description) {
    return level.equals(Level.DEBUG);
  }

  @Override
  public boolean postProcess(Data data) {
    return false;
  }
}

Config config = ConfigBuilder.withAccessToken("<post_server_item_access_token>"))
        .environment("development")
        .codeVersion("1.0.0")
        .filter(new FilterDebugItems())
        .build();

Features

Disable sending error data to Rollbar

If you don't want to send error data to Rollbar, set the enabled flag to false.

Config config = ConfigBuilder.withAccessToken("<post_server_item_access_token>"))
        .environment("development")
        .codeVersion("1.0.0")
        .enabled(false)
        .build();

Person Tracking

If your application has authenticated users, you can track which user ("person" in Rollbar parlance) was associated with each event.

public class MyPersonProvider implements Provider<Person> {

  @Override
  public Person provide() {
    return new Person.Builder()
        .id("84935784903")
        .email("janedoe@gmail.com")
        .username("janedoe1234")
        .build();
  }
} 

Config config = ConfigBuilder.withAccessToken("<access_token>"))
       .environment("development")
       .codeVersion("1.0.0")
       .person(new MyPersonProvider())
       .build();

Note: in Rollbar, the id is used to uniquely identify a person; email and username are supplemental and will be overwritten whenever a new value is received for an existing id. The id is a string up to 40 characters long. By default we only attempt to capture the id for a user.

Synchronous option

By default, the client sends items asynchronously. You can disable this, and send items synchronously if you wish.

Config config = ConfigBuilder.withAccessToken("<access_token>"))
        .environment("development")
        .codeVersion("1.0.0")
        .sender(new SyncSender.Builder()
            .build())
        .build();

Help / Support

If you run into any issues, please email us at support@rollbar.com.

For bug reports, please open an issue on GitHub.

Java


Rollbar SDK for Java and Android

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.