Merge branch 'main' into markushi/fix/frame-metrics-listener

Author: markushi

.cursor/rules/offline.mdc

@@ -0,0 +1,87 @@
+---
+alwaysApply: true
+description: Java SDK Offline behaviour
+---
+# Java SDK Offline behaviour
+
+By default offline caching is enabled for Android but disabled for JVM.
+It can be enabled by setting SentryOptions.cacheDirPath.
+
+For Android, AndroidEnvelopeCache is used. For JVM, if cache path has been configured, EnvelopeCache will be used.
+
+Any error, event, transaction, profile, replay etc. is turned into an envelope and then sent into ITransport.send.
+The default implementation is AsyncHttpTransport.
+
+If an envelope is dropped due to rate limit and has previously been cached (Cached hint) it will be discarded from the IEnvelopeCache.
+
+AsyncHttpTransport.send will enqueue an AsyncHttpTransport.EnvelopeSender task onto an executor.
+
+Any envelope that doesn't have the Cached hint will be stored in IEnvelopeCache by the EventSender task. Previously cached envelopes (Cached hint) will have a noop cache passed to AsyncHttpTransport.EnvelopeSender and thus not cache again. It is also possible cache is disabled in general.
+
+An envelope being sent directly from SDK API like Sentry.captureException will not have the Retryable hint.
+
+In case the SDK is offline, it'll mark the envelope to be retried if it has the Retryable hint.
+If the envelope is not retryable and hasn't been sent to offline cache, it's recorded as lost in a client report.
+
+In case the envelope can't be sent due to an error or network connection problems it'll be marked for retry if it has the Retryable hint.
+If it's not retryable and hasn't been cached, it's recorded as lost in a client report.
+
+In case the envelope is sent successfully, it'll be discarded from cache.
+
+The SDK has multiple mechanisms to deal with envelopes on disk.
+- OutboxSender: Sends events coming from other SDKs like NDK that wrote them to disk.
+- io.sentry.EnvelopeSender: This is the offline cache.
+
+Both of these are set up through an integration (SendCachedEnvelopeIntegration) which is configured to use SendFireAndForgetOutboxSender or SendFireAndForgetEnvelopeSender.
+
+io.sentry.EnvelopeSender is able to pick up files in the cache directory and send them.
+It will trigger sending envelopes in cache dir on init and when the connection status changes (e.g. the SDK comes back online, meaning it has Internet connection again).
+
+## When Envelope Files Are Removed From Cache
+
+Envelope files are removed from the cache directory in the following scenarios:
+
+### 1. Successful Send to Sentry Server
+When `AsyncHttpTransport` successfully sends an envelope to the Sentry server, it calls `envelopeCache.discard(envelope)` to remove the cached file. This happens in `AsyncHttpTransport.EnvelopeSender.flush()` when `result.isSuccess()` is true.
+
+### 2. Rate Limited Previously Cached Envelopes
+If an envelope is dropped due to rate limiting **and** has previously been cached (indicated by the `Cached` hint), it gets discarded immediately via `envelopeCache.discard(envelope)` in `AsyncHttpTransport.send()`.
+In this case the discarded envelope is recorded as lost in client reports.
+
+### 3. Offline Cache Processing (EnvelopeSender)
+When the SDK processes cached envelope files from disk (via `EnvelopeSender`), files are deleted after processing **unless** they are marked for retry. In `EnvelopeSender.processFile()`, the file is deleted with `safeDelete(file)` if `!retryable.isRetry()`.
+
+### 4. Session File Management
+Session-related files (session.json, previous_session.json) are removed during session lifecycle events like session start/end and abnormal exits.
+
+### 5. Cache rotation
+If the number of files in the cache directory has reached the configured limit (SentryOptions.maxCacheItems), the oldest file will be deleted to make room.
+This happens in `CacheStrategy.rotateCacheIfNeeded`. The deleted envelope will be recorded as lost in client reports.
+
+## Retry Mechanism
+
+**Important**: The SDK does NOT implement a traditional "max retry count" mechanism. Instead:
+
+### Infinite Retry Approach
+- **Retryable envelopes**: Stay in cache indefinitely and are retried when conditions improve (network connectivity restored, rate limits expire, etc.)
+- **Non-retryable envelopes**: If they fail to send, they're immediately recorded as lost (not cached for retry)
+
+### When Envelopes Are Permanently Lost (Not Due to Retry Limits)
+
+1. **Queue Overflow**: When the transport executor queue is full - recorded as `DiscardReason.QUEUE_OVERFLOW`
+
+2. **Network Errors (Non-Retryable)**: When an envelope isn't marked as retryable and fails due to network issues - recorded as `DiscardReason.NETWORK_ERROR`
+
+3. **Rate Limiting**: When envelope items are dropped due to active rate limits - recorded as `DiscardReason.RATELIMIT_BACKOFF`
+
+4. **Cache Overflow**: When the cache directory has reached maxCacheItems, old files are deleted - recorded as `DiscardReason.CACHE_OVERFLOW`
+
+### Cache Processing Triggers
+Cached envelopes are processed when:
+- Network connectivity is restored (via connection status observer)
+- SDK initialization occurs
+- Rate limits expire
+- Manual flush operations
+
+### File Deletion Implementation
+The actual file deletion is handled by `EnvelopeCache.discard()` which calls `envelopeFile.delete()` and logs errors if deletion fails.

.github/workflows/release-build.yml

@@ -39,4 +39,3 @@ jobs:
           path: |
             ./*/build/distributions/*.zip
             ./sentry-opentelemetry/*/build/distributions/*.zip
-            ./sentry-android-ndk/build/intermediates/merged_native_libs/release/out/lib/*

CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## Unreleased
 
+### Improvements
+
+- Session Replay: Use main thread looper to schedule replay capture ([#4542](https://github.com/getsentry/sentry-java/pull/4542))
+- Use single `LifecycleObserver` and multi-cast it to the integrations interested in lifecycle states ([#4567](https://github.com/getsentry/sentry-java/pull/4567))
+
+### Fixes
+
+- Cache network capabilities and status to reduce IPC calls ([#4560](https://github.com/getsentry/sentry-java/pull/4560))
+- Deduplicate battery breadcrumbs ([#4561](https://github.com/getsentry/sentry-java/pull/4561))
+- Remove unused method in ManifestMetadataReader ([#4585](https://github.com/getsentry/sentry-java/pull/4585))
+- Have single `NetworkCallback` registered at a time to reduce IPC calls ([#4562](https://github.com/getsentry/sentry-java/pull/4562))
+- Limit ProGuard keep rules for native methods within `sentry-android-ndk` to the `io.sentry.**` namespace. ([#4427](https://github.com/getsentry/sentry-java/pull/4427))
+  - If you relied on the Sentry SDK to keep native method names for JNI compatibility within your namespace, please review your ProGuard rules and ensure the configuration still works. Especially when you're not consuming any of the default Android proguard rules (`proguard-android.txt` or `proguard-android-optimize.txt`) the following config should be present:
+  ```
+  -keepclasseswithmembernames class * {
+    native <methods>;
+  }
+  ```
+
+## 8.18.0
+
 ### Features
 
 - Add `SentryUserFeedbackButton` Composable ([#4559](https://github.com/getsentry/sentry-java/pull/4559))

gradle.properties

@@ -11,7 +11,7 @@ org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
 android.useAndroidX=true
 
 # Release information
-versionName=8.17.0
+versionName=8.18.0
 
 # Override the SDK name on native crashes on Android
 sentryAndroidSdkName=sentry.native.android

scripts/update-gradle.sh

@@ -32,10 +32,6 @@ set-version)
         version="${version:1}"
     fi
 
-    # Remove trailing ".0" - gradlew expects '7.1' instead of '7.1.0'
-    if [[ "$version" == *".0" ]]; then
-        version="${version:0:${#version}-2}"
-    fi
     echo "Setting gradle version to '$version'"
 
     # This sets version to gradle-wrapper.properties.

sentry-android-core/api/sentry-android-core.api

@@ -166,11 +166,17 @@ public final class io/sentry/android/core/AppLifecycleIntegration : io/sentry/In
 	public fun register (Lio/sentry/IScopes;Lio/sentry/SentryOptions;)V
 }
 
-public final class io/sentry/android/core/AppState {
+public final class io/sentry/android/core/AppState : java/io/Closeable {
+	public fun close ()V
 	public static fun getInstance ()Lio/sentry/android/core/AppState;
 	public fun isInBackground ()Ljava/lang/Boolean;
 }
 
+public abstract interface class io/sentry/android/core/AppState$AppStateListener {
+	public abstract fun onBackground ()V
+	public abstract fun onForeground ()V
+}
+
 public final class io/sentry/android/core/BuildConfig {
 	public static final field BUILD_TYPE Ljava/lang/String;
 	public static final field DEBUG Z
@@ -263,7 +269,7 @@ public final class io/sentry/android/core/NdkIntegration : io/sentry/Integration
 }
 
 public final class io/sentry/android/core/NetworkBreadcrumbsIntegration : io/sentry/Integration, java/io/Closeable {
-	public fun <init> (Landroid/content/Context;Lio/sentry/android/core/BuildInfoProvider;Lio/sentry/ILogger;)V
+	public fun <init> (Landroid/content/Context;Lio/sentry/android/core/BuildInfoProvider;)V
 	public fun close ()V
 	public fun register (Lio/sentry/IScopes;Lio/sentry/SentryOptions;)V
 }
@@ -422,11 +428,13 @@ public class io/sentry/android/core/SpanFrameMetricsCollector : io/sentry/IPerfo
 	public fun onSpanStarted (Lio/sentry/ISpan;)V
 }
 
-public final class io/sentry/android/core/SystemEventsBreadcrumbsIntegration : io/sentry/Integration, java/io/Closeable {
+public final class io/sentry/android/core/SystemEventsBreadcrumbsIntegration : io/sentry/Integration, io/sentry/android/core/AppState$AppStateListener, java/io/Closeable {
 	public fun <init> (Landroid/content/Context;)V
 	public fun <init> (Landroid/content/Context;Ljava/util/List;)V
 	public fun close ()V
 	public static fun getDefaultActions ()Ljava/util/List;
+	public fun onBackground ()V
+	public fun onForeground ()V
 	public fun register (Lio/sentry/IScopes;Lio/sentry/SentryOptions;)V
 }
 

sentry-android-core/src/main/java/io/sentry/android/core/AndroidOptionsInitializer.java

@@ -28,6 +28,7 @@
 import io.sentry.android.core.internal.gestures.AndroidViewGestureTargetLocator;
 import io.sentry.android.core.internal.modules.AssetsModulesLoader;
 import io.sentry.android.core.internal.util.AndroidConnectionStatusProvider;
+import io.sentry.android.core.internal.util.AndroidCurrentDateProvider;
 import io.sentry.android.core.internal.util.AndroidThreadChecker;
 import io.sentry.android.core.internal.util.SentryFrameMetricsCollector;
 import io.sentry.android.core.performance.AppStartMetrics;
@@ -127,6 +128,7 @@ static void loadDefaultAndMetadataOptions(
     options.setCacheDirPath(getCacheDir(context).getAbsolutePath());
 
     readDefaultOptionValues(options, context, buildInfoProvider);
+    AppState.getInstance().registerLifecycleObserver(options);
   }
 
   @TestOnly
@@ -157,7 +159,8 @@ static void initializeIntegrationsAndProcessors(
 
     if (options.getConnectionStatusProvider() instanceof NoOpConnectionStatusProvider) {
       options.setConnectionStatusProvider(
-          new AndroidConnectionStatusProvider(context, options.getLogger(), buildInfoProvider));
+          new AndroidConnectionStatusProvider(
+              context, options, buildInfoProvider, AndroidCurrentDateProvider.getInstance()));
     }
 
     if (options.getCacheDirPath() != null) {
@@ -380,8 +383,7 @@ static void installDefaultIntegrations(
     }
     options.addIntegration(new AppComponentsBreadcrumbsIntegration(context));
     options.addIntegration(new SystemEventsBreadcrumbsIntegration(context));
-    options.addIntegration(
-        new NetworkBreadcrumbsIntegration(context, buildInfoProvider, options.getLogger()));
+    options.addIntegration(new NetworkBreadcrumbsIntegration(context, buildInfoProvider));
     if (isReplayAvailable) {
       final ReplayIntegration replay =
           new ReplayIntegration(context, CurrentDateProvider.getInstance());

sentry-android-core/src/main/java/io/sentry/android/core/AppLifecycleIntegration.java

@@ -2,12 +2,12 @@
 
 import static io.sentry.util.IntegrationUtils.addIntegrationToSdkVersion;
 
-import androidx.lifecycle.ProcessLifecycleOwner;
 import io.sentry.IScopes;
+import io.sentry.ISentryLifecycleToken;
 import io.sentry.Integration;
 import io.sentry.SentryLevel;
 import io.sentry.SentryOptions;
-import io.sentry.android.core.internal.util.AndroidThreadChecker;
+import io.sentry.util.AutoClosableReentrantLock;
 import io.sentry.util.Objects;
 import java.io.Closeable;
 import java.io.IOException;
@@ -17,20 +17,11 @@
 
 public final class AppLifecycleIntegration implements Integration, Closeable {
 
+  private final @NotNull AutoClosableReentrantLock lock = new AutoClosableReentrantLock();
   @TestOnly @Nullable volatile LifecycleWatcher watcher;
 
   private @Nullable SentryAndroidOptions options;
 
-  private final @NotNull MainLooperHandler handler;
-
-  public AppLifecycleIntegration() {
-    this(new MainLooperHandler());
-  }
-
-  AppLifecycleIntegration(final @NotNull MainLooperHandler handler) {
-    this.handler = handler;
-  }
-
   @Override
   public void register(final @NotNull IScopes scopes, final @NotNull SentryOptions options) {
     Objects.requireNonNull(scopes, "Scopes are required");
@@ -55,85 +46,47 @@ public void register(final @NotNull IScopes scopes, final @NotNull SentryOptions
 
     if (this.options.isEnableAutoSessionTracking()
         || this.options.isEnableAppLifecycleBreadcrumbs()) {
-      try {
-        Class.forName("androidx.lifecycle.DefaultLifecycleObserver");
-        Class.forName("androidx.lifecycle.ProcessLifecycleOwner");
-        if (AndroidThreadChecker.getInstance().isMainThread()) {
-          addObserver(scopes);
-        } else {
-          // some versions of the androidx lifecycle-process require this to be executed on the main
-          // thread.
-          handler.post(() -> addObserver(scopes));
+      try (final ISentryLifecycleToken ignored = lock.acquire()) {
+        if (watcher != null) {
+          return;
         }
-      } catch (ClassNotFoundException e) {
-        options
-            .getLogger()
-            .log(
-                SentryLevel.WARNING,
-                "androidx.lifecycle is not available, AppLifecycleIntegration won't be installed");
-      } catch (IllegalStateException e) {
-        options
-            .getLogger()
-            .log(SentryLevel.ERROR, "AppLifecycleIntegration could not be installed", e);
-      }
-    }
-  }
 
-  private void addObserver(final @NotNull IScopes scopes) {
-    // this should never happen, check added to avoid warnings from NullAway
-    if (this.options == null) {
-      return;
-    }
+        watcher =
+            new LifecycleWatcher(
+                scopes,
+                this.options.getSessionTrackingIntervalMillis(),
+                this.options.isEnableAutoSessionTracking(),
+                this.options.isEnableAppLifecycleBreadcrumbs());
 
-    watcher =
-        new LifecycleWatcher(
-            scopes,
-            this.options.getSessionTrackingIntervalMillis(),
-            this.options.isEnableAutoSessionTracking(),
-            this.options.isEnableAppLifecycleBreadcrumbs());
+        AppState.getInstance().addAppStateListener(watcher);
+      }
 
-    try {
-      ProcessLifecycleOwner.get().getLifecycle().addObserver(watcher);
       options.getLogger().log(SentryLevel.DEBUG, "AppLifecycleIntegration installed.");
       addIntegrationToSdkVersion("AppLifecycle");
-    } catch (Throwable e) {
-      // This is to handle a potential 'AbstractMethodError' gracefully. The error is triggered in
-      // connection with conflicting dependencies of the androidx.lifecycle.
-      // //See the issue here: https://github.com/getsentry/sentry-java/pull/2228
-      watcher = null;
-      options
-          .getLogger()
-          .log(
-              SentryLevel.ERROR,
-              "AppLifecycleIntegration failed to get Lifecycle and could not be installed.",
-              e);
     }
   }
 
   private void removeObserver() {
-    final @Nullable LifecycleWatcher watcherRef = watcher;
+    final @Nullable LifecycleWatcher watcherRef;
+    try (final ISentryLifecycleToken ignored = lock.acquire()) {
+      watcherRef = watcher;
+      watcher = null;
+    }
+
     if (watcherRef != null) {
-      ProcessLifecycleOwner.get().getLifecycle().removeObserver(watcherRef);
+      AppState.getInstance().removeAppStateListener(watcherRef);
       if (options != null) {
         options.getLogger().log(SentryLevel.DEBUG, "AppLifecycleIntegration removed.");
       }
     }
-    watcher = null;
   }
 
   @Override
   public void close() throws IOException {
-    if (watcher == null) {
-      return;
-    }
-    if (AndroidThreadChecker.getInstance().isMainThread()) {
-      removeObserver();
-    } else {
-      // some versions of the androidx lifecycle-process require this to be executed on the main
-      // thread.
-      // avoid method refs on Android due to some issues with older AGP setups
-      // noinspection Convert2MethodRef
-      handler.post(() -> removeObserver());
-    }
+    removeObserver();
+    // TODO: probably should move it to Scopes.close(), but that'd require a new interface and
+    //  different implementations for Java and Android. This is probably fine like this too, because
+    //  integrations are closed in the same place
+    AppState.getInstance().unregisterLifecycleObserver();
   }
 }