Migration Guide

Migrating from io.sentry:sentry-android 6.14.x to io.sentry:sentry-android 6.15.0

The sentry-compose-android and sentry-compose integrations now declare their upstream dependencies as compileOnly. Make sure to have the androidx.navigation:navigation-compose, androidx.compose.runtime:runtime, and androidx.compose.ui:ui dependencies on the classpath if you're using those integrations. Otherwise, the application will crash with a NoClassDefFoundError exception.

Migrating from io.sentry:sentry-android 6.2.x to io.sentry:sentry-android 6.3.0

The sentry-android-okhttp, sentry-android-fragment, and sentry-android-timber integrations now declare their upstream dependencies as compileOnly. Make sure to have the okhttp, fragment, and timber dependencies on the classpath if you're using those integrations or the application will crash with a NoClassDefFoundError exception.

Migrating from io.sentry:sentry-android 6.x to io.sentry:sentry-android 6.2.0

• Kotlin plugin is upgraded to 1.6.10.

This version is still compatible with Kotlin 1.4.

Migrating from io.sentry:sentry-android 5.x to io.sentry:sentry-android 6.0.0

• Kotlin plugin is upgraded to 1.5.

• Kotlin languageVersion is upgraded to 1.4.

• Gson is removed as a transitive dependency and vendored in the SDK.

  • Protocol classes now implement the JsonSerializable and JsonDeserializer interfaces.

• SentryOptions#shutdownTimeout is renamed to shutdownTimeoutMillis.

• Removed @Deprecated and @ApiStatus.ScheduledForRemoval methods

  • ITransaction#setRequest
  • ITransaction#getRequest
  • ITransaction#getContexts
  • SentryBaseEvent#getOriginThrowable
  • SentryOptions#getCacheDirSize
  • SentryOptions#setCacheDirSize
  • SentryOptions#isEnableSessionTracking
  • SentryOptions#setEnableSessionTracking

• Removed unnecessary abstractions

  • IBuildInfoProvider is now BuildInfoProvider only.
  • IHandler is now MainLooperHandler only.

• ISpan now has higher precision using the System#nanoTime instead of milliseconds.

• Hints changed its type from Object to io.sentry.Hint

Old:

Sentry.captureException(RuntimeException("exception"), "myStringHint")

New:

val hints = mutableMapOf<String, Any>("myHint" to "myStringHint")
Sentry.captureException(RuntimeException("exception"), hints)

• SentryOptions#enableScopeSync is now enabled by default, to disable it, see the code snippet bellow.

<meta-data android:name="io.sentry.ndk.scope-sync.enable" android:value="false" />

• SentryOptions#sendClientReports is now enabled by default. To disable it, use the code snippet below:

<meta-data android:name="io.sentry.send-client-reports" android:value="false" />

Sentry Self-hosted Compatibility

• Starting with version 6.0.0 of sentry, Sentry's version >= v21.9.0 is required or you have to manually disable sending client reports via the sendClientReports option. This only applies to self-hosted Sentry. If you are using sentry.io, no action is needed.

There are more changes and refactors, but they are not user breaking changes.

Migrating to io.sentry:sentry-android-timber 5.6.2

Starting from version 5.6.2, the Timber.tag usage is no longer supported by our SDK (the tag will not be captured and reflected on Sentry). Please, vote on this GitHub issue to let us know if we should provide support for that.

Migrating from io.sentry:sentry-android-gradle-plugin 2.x to io.sentry:sentry-android-gradle-plugin 3.0.0

The io.sentry.android.gradle >= 3.0.0 requires Android Gradle Plugin >= 7.0.0. For older versions of the Android Gradle Plugin, use io.sentry.android.gradle:2.+.

includeProguardMapping

The autoUpload flag has been deprecated in favor of two new options:

• includeProguardMapping - Disables/enables Proguard mapping functionality. When enabled, generates a UUID and attempts to upload a Proguard mapping associated with that UUID to Sentry. When autoUploadProguardMapping is disabled, the plugin will only generate a sentry-debug-meta.properties file containg UUID, which can later be used to manually upload the mapping using, for example sentry-cli.
• autoUploadProguardMapping - Defines whether the gradle plugin should attempt to auto-upload the mapping file to Sentry. When includeProguardMapping is disabled, this flag has no effect.

Old:

sentry {
    autoUpload = false
}

New:

sentry {
  includeProguardMapping = true
  autoUploadProguardMapping = false
}

tracingInstrumentation

The io.sentry.android.gradle enables the

sentry {
    // Enable or disable the tracing instrumentation.
    // Does auto instrumentation for 'androidx.sqlite' and 'androidx.room' libraries.
    // It starts and finishes a Span within any CRUD operation.
    // Default is enabled.
    // Only available v3.0.0 and above.
    tracingInstrumentation {
      enabled = false
    }
}

Migrating from io.sentry:sentry-android-gradle-plugin 1.x to io.sentry:sentry-android-gradle-plugin 2.0.0

The io.sentry.android.gradle >= 2.0.0 requires Android Gradle Plugin >= 4.0.0.

The io.sentry.android.gradle >= 2.0.0 must be applied to the app/build.gradle module (or the module that has com.android.application plugin applied).

The io.sentry.android.gradle >= 2.0.0 publishes the Gradle Plugin Marker to Maven Central. As a result, you no longer need to set the classpath.

Old:

buildscript {
    repositories {
        mavenCentral()
    }

    dependencies {
        classpath 'io.sentry:sentry-android-gradle-plugin:{version}'
    }
}

apply plugin: 'io.sentry.android.gradle'

New:

plugins {
    id "io.sentry.android.gradle" version "{version}"
}

buildscript {
    repositories {
        mavenCentral()
    }
}

The io.sentry.android.gradle has been rewritten in Kotlin. As a result, the Groovy or Kotlin DSL syntax has slightly changed.

The autoProguardConfig flag has been removed, the Android SDK >= 2.0.0 version already merges the ProGuard rules automatically.

Old:

sentry {
    autoProguardConfig false
    autoUpload true
    uploadNativeSymbols false
    includeNativeSources false
}

New:

sentry {
    autoUpload = true
    uploadNativeSymbols = false
    includeNativeSources = false
}

Migrating from io.sentry:sentry-android 4.3.0 to io.sentry:sentry-android 5.0.0

You may remove android:extractNativeLibs="true" meta-data in the AndroidManifest file or android.bundle.enableUncompressedNativeLibs=false in the gradle.properties file if you're using the Android Native Development Kit. Sentry can now symbolicate events with the default value of extractNativeLibs and android.bundle.enableUncompressedNativeLibs.

Sentry#startTransaction by default does not bind created transaction to the scope. To start transaction with binding to the scope, use one of the new overloaded startTransaction methods taking bindToScope parameter and set it to true. Bound transaction can be retrieved with Sentry#getSpan.

All SDK methods have been annotated with JetBrains Annotations: @Nullable and @NotNull. Kotlin compiler respects these annotations, so in Kotlin code, some fields that were recognized as not-null, are now nullable, and the other way around.

SentryBaseEvent#getOriginThrowable has been deprecated in favor of SentryBaseEvent#getThrowable, and SentryBaseEvent#getThrowable now returns the unwrapped throwable.

SentryOptions#getCacheDirSize has been deprecated in favor of SentryOptions#getMaxCacheItems.

InvalidDsnException has been removed. It is replaced by IllegalArgumentException.

EventProcessor interface has a new default method which could break the instantiation when using trailing lambdas.

Old:

SentryOptions#addEventProcessor { event, _ -> event }

New:

SentryOptions#addEventProcessor(object : EventProcessor {
    override fun process(event: SentryEvent, hint: Hint): SentryEvent? {
        return event
    }
})

A random generated installationId replaces Settings.Secure.ANDROID_ID, which has been removed. This may affect the number of unique users displayed on the the Issues page and Alerts. If you always set a custom user using Sentry.setUser(customUser), the behavior has not changed. While you don't have to make any update, if you want to maintain the old behavior, use the following code snippet:

User user = new User();
user.setId(Settings.Secure.ANDROID_ID);

Sentry.setUser(user);

SentryOptions#setEnableSessionTracking(boolean) is deprecated in favor of SentryOptions#setEnableAutoSessionTracking(boolean). It will be removed in future.

Old:

SentryAndroid.init(this, options -> {
    options.setEnableSessionTracking(false);
});

New:

SentryAndroid.init(this, options -> {
    options.setEnableAutoSessionTracking(false);
});

io.sentry.session-tracking.enable AndroidManifest meta-data is deprecated in favor of io.sentry.auto-session-tracking.enable. It will be removed in future.

Old:

<application>
    <meta-data android:name="io.sentry.session-tracking.enable" android:value="false" />
</application>

New:

<application>
    <meta-data android:name="io.sentry.auto-session-tracking.enable" android:value="false" />
</application>

Migrating from io.sentry:sentry-android 4.1.0 to io.sentry:sentry-android 4.2.0

operation is now a required property of the SentryTransaction and SentrySpan. Whenever a transaction or span is started, the value for operation must be provided:

Sentry.startTransaction("transaction-name", "operation-name");

Migrating from io.sentry:sentry-android 2.x to io.sentry:sentry-android 3.x

Package changes

The package io.sentry.core has been renamed to io.sentry. To compile correctly, replace the strings on all the usages from io.sentry.core. to io.sentry.

Other than that, the APIs didn't change. Release Heath sets by default. If you prefer not to track the health of your releases, disable it with:

<application>
  <meta-data android:name="io.sentry.session-tracking.enable" android:value="false" />
</application>

Migrating from io.sentry:sentry-android 1.x to io.sentry:sentry-android 2.x

With Sentry Android, we've updated the API to resemble the Unified API more closely. And now that the SDK isn't built on top of io.sentry:sentry-java, Sentry Android has more Android-specific features.

If you want to upgrade from the previous version of the SDK, please check the following sections of changes that may need updating in your code.

Configuration

The file sentry.properties used by the previous version of the SDK has been discontinued. Configurations for the new SDK are in AndroidManifest.xml or directly in the code.

Example of the configuration in the Manifest:

<application>
    <!-- Example of the Sentry DSN setting -->
    <meta-data android:name="io.sentry.dsn" android:value="https://examplePublicKey@o0.ingest.sentry.io/0" />
</application>

If you want to set the configuration manually in the code, you need to initialize the SDK with SentryAndroid.init() --- described in Installation --- in the same file as SentryAndroidOptions, which holds configuration items.

Installation

The new SDK can initialize automatically, all you need to do is provide the DSN in your Manifest file, as shown in the previous example in Configuration.

Manual Installation

If you want to register any callback to filter and modify events and/or breadcrumbs, or if you want to provide the configuration values via code, you need to initialize the SDK using the SentryAndroid.init().

To initialize the SDK manually:

• Disable the auto-init feature by providing the following line in the manifest:

  Xml

  Copied

  <application>
      <meta-data android:name="io.sentry.auto-init" android:value="false" />
  </application>

• Initialize the SDK directly in your application:

  JavaKotlin

  Copied

  SentryAndroid.init(this, options -> {
    options.setDsn("https://examplePublicKey@o0.ingest.sentry.io/0");
  });

Releases

Please note that the new SDK will send with each event a release version in a different format than the previous SDK.

If you are using the GitHub or GitLab integrations, you need to do one of the following:

• Use the new format
• Set the release in your AndroidManifest.xml
• Change your code as described in the configuration section

API

Set tag

Old:

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

New:

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

Capture custom exception

Old:

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

Old:

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

Old:

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

New:

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

User

Old:

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

Old:

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

New:

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

Clear the Context/Scope

Old:

Sentry.clearContext();

New:

Sentry.configureScope(s -> s.clear());

Sentry Gradle Plugin

Disable the autoProguardConfig flag from the Sentry Gradle Plugin since io.sentry:sentry-android >= 2.0.0 does this automatically.

sentry {
    autoProguardConfig false
}