feat(android-ndk): add api for getting debug images by addresses

CHANGELOG.md

@@ -11,6 +11,10 @@
 - (Jetpack Compose) Modifier.sentryTag now uses Modifier.Node ([#4029](https://github.com/getsentry/sentry-java/pull/4029))
     - This allows Composables that use this modifier to be skippable
 
+### Features
+
+- (Internal) Add API to filter native debug images based on stacktrace addresses ([#4159](https://github.com/getsentry/sentry-java/pull/4159))
+
 ## 7.21.0
 
 ### Fixes

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

@@ -208,6 +208,7 @@ public abstract class io/sentry/android/core/EnvelopeFileObserverIntegration : i
 public abstract interface class io/sentry/android/core/IDebugImagesLoader {
 	public abstract fun clearDebugImages ()V
 	public abstract fun loadDebugImages ()Ljava/util/List;
+	public abstract fun loadDebugImagesForAddresses (Ljava/util/Set;)Ljava/util/Set;
 }
 
 public final class io/sentry/android/core/InternalSentrySdk {

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

@@ -2,6 +2,7 @@
 
 import io.sentry.protocol.DebugImage;
 import java.util.List;
+import java.util.Set;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Nullable;
 
@@ -11,5 +12,8 @@ public interface IDebugImagesLoader {
   @Nullable
   List<DebugImage> loadDebugImages();
 
+  @Nullable
+  Set<DebugImage> loadDebugImagesForAddresses(Set<String> addresses);
+
   void clearDebugImages();
 }

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

@@ -2,6 +2,7 @@
 
 import io.sentry.protocol.DebugImage;
 import java.util.List;
+import java.util.Set;
 import org.jetbrains.annotations.Nullable;
 
 final class NoOpDebugImagesLoader implements IDebugImagesLoader {
@@ -19,6 +20,11 @@ public static NoOpDebugImagesLoader getInstance() {
     return null;
   }
 
+  @Override
+  public @Nullable Set<DebugImage> loadDebugImagesForAddresses(Set<String> addresses) {
+    return null;
+  }
+
   @Override
   public void clearDebugImages() {}
 }

sentry-android-core/src/test/java/io/sentry/android/core/SentryAndroidOptionsTest.kt

@@ -182,6 +182,8 @@ class SentryAndroidOptionsTest {
 
     private class CustomDebugImagesLoader : IDebugImagesLoader {
         override fun loadDebugImages(): List<DebugImage>? = null
+        override fun loadDebugImagesForAddresses(addresses: Set<String>?): Set<DebugImage>? = null
+
         override fun clearDebugImages() {}
     }
 }

sentry-android-ndk/api/sentry-android-ndk.api

@@ -10,6 +10,7 @@ public final class io/sentry/android/ndk/DebugImagesLoader : io/sentry/android/c
 	public fun <init> (Lio/sentry/android/core/SentryAndroidOptions;Lio/sentry/android/ndk/NativeModuleListLoader;)V
 	public fun clearDebugImages ()V
 	public fun loadDebugImages ()Ljava/util/List;
+	public fun loadDebugImagesForAddresses (Ljava/util/Set;)Ljava/util/Set;
 }
 
 public final class io/sentry/android/ndk/NdkScopeObserver : io/sentry/ScopeObserverAdapter {

sentry-android-ndk/src/main/java/io/sentry/android/ndk/DebugImagesLoader.java

@@ -6,8 +6,9 @@
 import io.sentry.android.core.SentryAndroidOptions;
 import io.sentry.protocol.DebugImage;
 import io.sentry.util.Objects;
-import java.util.Arrays;
+import java.util.HashSet;
 import java.util.List;
+import java.util.Set;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 import org.jetbrains.annotations.VisibleForTesting;
@@ -22,7 +23,7 @@ public final class DebugImagesLoader implements IDebugImagesLoader {
 
   private final @NotNull NativeModuleListLoader moduleListLoader;
 
-  private static @Nullable List<DebugImage> debugImages;
+  private static volatile @Nullable List<DebugImage> debugImages;
 
   /** we need to lock it because it could be called from different threads */
   private static final @NotNull Object debugImagesLock = new Object();
@@ -60,7 +61,92 @@ public DebugImagesLoader(
     return debugImages;
   }
 
-  /** Clears the caching of debug images on sentry-native and here. */
+  /**
+   * Loads debug images for the given set of addresses.
+   *
+   * @param addresses Set of memory addresses to find debug images for
+   * @return Set of matching debug images, or null if debug images couldn't be loaded
+   */
+  public @Nullable Set<DebugImage> loadDebugImagesForAddresses(
+      final @NotNull Set<String> addresses) {
+    try (final @NotNull ISentryLifecycleToken ignored = debugImagesLock.acquire()) {
+      final @Nullable List<DebugImage> allDebugImages = loadDebugImages();
+      if (allDebugImages == null) {
+        return null;
+      }
+      if (addresses.isEmpty()) {
+        return null;
+      }
+
+      final Set<DebugImage> referencedImages = filterImagesByAddresses(allDebugImages, addresses);
+      if (referencedImages.isEmpty()) {
+        options
+            .getLogger()
+            .log(
+                SentryLevel.WARNING,
+                "No debug images found for any of the %d addresses.",
+                addresses.size());
+        return null;
+      }
+
+      return referencedImages;
+    }
+  }
+
+  /**
+   * Finds all debug image containing the given addresses. Assumes that the images are sorted by
+   * address, which should always be true on Linux/Android and Windows platforms
+   *
+   * @return All matching debug images or null if none are found
+   */
+  private @NotNull Set<DebugImage> filterImagesByAddresses(
+      final @NotNull List<DebugImage> images, final @NotNull Set<String> addresses) {
+    final Set<DebugImage> result = new HashSet<>();
+
+    for (int i = 0; i < images.size(); i++) {
+      final @NotNull DebugImage image = images.get(i);
+      final @Nullable DebugImage nextDebugImage =
+          (i + 1) < images.size() ? images.get(i + 1) : null;
+      final @Nullable String nextDebugImageAddress =
+          nextDebugImage != null ? nextDebugImage.getImageAddr() : null;
+
+      for (final @NotNull String rawAddress : addresses) {
+        try {
+          final long address = Long.parseLong(rawAddress.replace("0x", ""), 16);
+
+          final @Nullable String imageAddress = image.getImageAddr();
+          if (imageAddress != null) {
+            try {
+              final long imageStart = Long.parseLong(imageAddress.replace("0x", ""), 16);
+              final long imageEnd;
+
+              final @Nullable Long imageSize = image.getImageSize();
+              if (imageSize != null) {
+                imageEnd = imageStart + imageSize;
+              } else if (nextDebugImageAddress != null) {
+                imageEnd = Long.parseLong(nextDebugImageAddress.replace("0x", ""), 16);
+              } else {
+                imageEnd = Long.MAX_VALUE;
+              }
+              if (address >= imageStart && address < imageEnd) {
+                result.add(image);
+                // once image is added we can skip the remaining addresses and go straight to the
+                // next
+                // image
+                break;
+              }
+            } catch (NumberFormatException e) {
+              // ignored, invalid debug image address
+            }
+          }
+        } catch (NumberFormatException e) {
+          // ignored, invalid address supplied
+        }
+      }
+    }
+    return result;
+  }
+
   @Override
   public void clearDebugImages() {
     synchronized (debugImagesLock) {

sentry-android-ndk/src/test/java/io/sentry/android/ndk/DebugImagesLoaderTest.kt

@@ -7,6 +7,7 @@ import org.mockito.kotlin.verify
 import org.mockito.kotlin.whenever
 import java.lang.RuntimeException
 import kotlin.test.Test
+import kotlin.test.assertEquals
 import kotlin.test.assertNotNull
 import kotlin.test.assertNull
 import kotlin.test.assertTrue
@@ -17,11 +18,13 @@ class DebugImagesLoaderTest {
         val options = SentryAndroidOptions()
 
         fun getSut(): DebugImagesLoader {
-            return DebugImagesLoader(options, nativeLoader)
+            val loader = DebugImagesLoader(options, nativeLoader)
+            loader.clearDebugImages()
+            return loader
         }
     }
 
-    private val fixture = Fixture()
+    private var fixture = Fixture()
 
     @Test
     fun `get images returns image list`() {
@@ -78,4 +81,107 @@ class DebugImagesLoaderTest {
 
         assertNull(sut.cachedDebugImages)
     }
+
+    @Test
+    fun `find images by address`() {
+        val sut = fixture.getSut()
+
+        val image1 = io.sentry.ndk.DebugImage().apply {
+            imageAddr = "0x1000"
+            imageSize = 0x1000L
+        }
+
+        val image2 = io.sentry.ndk.DebugImage().apply {
+            imageAddr = "0x2000"
+            imageSize = 0x1000L
+        }
+
+        val image3 = io.sentry.ndk.DebugImage().apply {
+            imageAddr = "0x3000"
+            imageSize = 0x1000L
+        }
+
+        whenever(fixture.nativeLoader.loadModuleList()).thenReturn(arrayOf(image1, image2, image3))
+
+        val result = sut.loadDebugImagesForAddresses(
+            setOf("0x1500", "0x2500")
+        )
+
+        assertNotNull(result)
+        assertEquals(2, result.size)
+        assertTrue(result.any { it.imageAddr == image1.imageAddr })
+        assertTrue(result.any { it.imageAddr == image2.imageAddr })
+    }
+
+    @Test
+    fun `find images with invalid addresses are not added to the result`() {
+        val sut = fixture.getSut()
+
+        val image1 = io.sentry.ndk.DebugImage().apply {
+            imageAddr = "0x1000"
+            imageSize = 0x1000L
+        }
+
+        val image2 = io.sentry.ndk.DebugImage().apply {
+            imageAddr = "0x2000"
+            imageSize = 0x1000L
+        }
+
+        whenever(fixture.nativeLoader.loadModuleList()).thenReturn(arrayOf(image1, image2))
+
+        val hexAddresses = setOf("0xINVALID", "0x1500")
+        val result = sut.loadDebugImagesForAddresses(hexAddresses)
+
+        assertEquals(1, result!!.size)
+    }
+
+    @Test
+    fun `find images by address returns null if result is empty`() {
+        val sut = fixture.getSut()
+
+        val image1 = io.sentry.ndk.DebugImage().apply {
+            imageAddr = "0x1000"
+            imageSize = 0x1000L
+        }
+
+        val image2 = io.sentry.ndk.DebugImage().apply {
+            imageAddr = "0x2000"
+            imageSize = 0x1000L
+        }
+
+        whenever(fixture.nativeLoader.loadModuleList()).thenReturn(arrayOf(image1, image2))
+
+        val hexAddresses = setOf("0x100", "0x10500")
+        val result = sut.loadDebugImagesForAddresses(hexAddresses)
+
+        assertNull(result)
+    }
+
+    @Test
+    fun `invalid image adresses are ignored for loadDebugImagesForAddresses`() {
+        val sut = fixture.getSut()
+
+        val image1 = io.sentry.ndk.DebugImage().apply {
+            imageAddr = "0xNotANumber"
+            imageSize = 0x1000L
+        }
+
+        val image2 = io.sentry.ndk.DebugImage().apply {
+            imageAddr = "0x2000"
+            imageSize = null
+        }
+
+        val image3 = io.sentry.ndk.DebugImage().apply {
+            imageAddr = "0x5000"
+            imageSize = 0x1000L
+        }
+
+        whenever(fixture.nativeLoader.loadModuleList()).thenReturn(arrayOf(image1, image2, image3))
+
+        val hexAddresses = setOf("0x100", "0x2000", "0x2000", "0x5000")
+        val result = sut.loadDebugImagesForAddresses(hexAddresses)
+
+        assertNotNull(result)
+        assertEquals(2, result.size)
+    }
 }