Migrating Version 1.x to 4.x

Migrating from io.sentry:sentry 1.x to io.sentry:sentry 4.x

Our update to the API follows the Unified API more closely. It's a completely updated code base, written to support our Android SDK.

API Changes

Set tag

Previous:

Sentry.getContext().addTag("tagName", "tagValue");

Updated:

Sentry.setTag("tagName", "tagValue");

Capture custom exception

Previous:

try {
  int x = 1 / 0;
} catch (Exception e) {
  Sentry.capture(e);
}

New:

try {
  int x = 1 / 0;
} catch (Exception e) {
  Sentry.captureException(e);
}

Capture a message

Previous:

Sentry.capture("This is a test");

New:

Sentry.captureMessage("This is a test"); // SentryLevel.INFO by default
Sentry.captureMessage("This is a test", SentryLevel.WARNING); // or specific level

Breadcrumbs

Previous:

Sentry.getContext().recordBreadcrumb(
  new BreadcrumbBuilder().setMessage("User made an action").build()
);

New:

Sentry.addBreadcrumb("User made an action");

User

Previous:

Sentry.getContext().setUser(
  new UserBuilder().setEmail("hello@sentry.io").build()
);

New:

User user = new User();
user.setEmail("hello@sentry.io");
Sentry.setUser(user);

Set extra

Previous:

Sentry.getContext().addExtra("extra", "thing");

New:

Sentry.setExtra("extra", "thing");

Removed Properties

Following configuration properties have been removed:

• buffer.dir - can be set with SentryOptions#cacheDirPath
• buffer.size - can be set with SentryOptions#cacheDirSize
• buffer.flushtime - can be set with SentryOptions#flushTimeoutMillis
• buffer.shutdowntimeout
• buffer.gracefulshutdown
• async
• async.shutdowntimeout - can be set with SentryOptions#shutdownTimeout
• async.gracefulshutdown
• async.queuesize - can be set with SentryOptions#maxQueueSize
• async.threads
• async.priority
• compression
• maxmessagelength
• factory
• mdcTags
• extra - can be set on the scope with Scope#extra

Property Name Changes

Following properties cannot be set anymore through external configuration and have to be set directly on SentryOptions object when initializing Sentry:

• sample.rate - through SentryOptions#sampleRate
• timeout - through SentryOptions#connectionTimeoutMillis and SentryOptions#readTimeoutMillis

See Configuration page to find all available configuration properties.

Tags

Previous:

tags=tag1:value1,tag2:value2

New:

tags.tag1=value1
tags.tag2=value2

“In Application” Stack Frames

stacktrace.app.packages=com.mycompany,com.other.name

New:

in-app-includes=com.mycompany,com.other.name

There is also an option to exclude certain packages from stack traces:

in-app-excludes=com.packages.to.exclude