feat(error-tracking): record exception steps synchronously

Author: ioannisj

posthog/src/main/java/com/posthog/PostHog.kt

@@ -710,16 +710,16 @@ public class PostHog private constructor(
             return
         }
 
-        // Capture the timestamp on the calling thread, before any dispatch.
         val timestamp = Date()
         val buffer = exceptionStepsBuffer ?: return
 
         try {
-            queueExecutor.execute {
-                buffer.add(message, timestamp, properties)
-            }
+            // Record synchronously on the calling thread (no background dispatch): a step
+            // recorded immediately before a crash must already be buffered when the
+            // uncaught-exception handler captures it. The work is bounded and cheap.
+            buffer.add(message, timestamp, properties)
         } catch (e: Throwable) {
-            // recording must never throw into the host app (e.g. executor rejected after close)
+            // recording must never throw into the host app
             config?.logger?.log("addExceptionStep has thrown an exception: $e.")
         }
     }

posthog/src/main/java/com/posthog/PostHogInterface.kt

@@ -108,12 +108,10 @@ public interface PostHogInterface : PostHogCoreInterface {
      * Recording never throws into the host app: an empty message is ignored with a
      * warning, and internal failures silently skip the step.
      *
-     * Recording is asynchronous so it never blocks the caller: the step is buffered
-     * on a background queue (the `$timestamp` is still captured at call time). A step
-     * recorded immediately before a programmatic [captureException] in the same call
-     * stack may therefore not yet be buffered when that exception is captured, and so
-     * may be absent from its `$exception_steps`. Steps recorded earlier in the
-     * session are unaffected.
+     * Recording is synchronous: the `$timestamp` is captured at call time and the step
+     * is normalized, byte-budget enforced, and buffered before this method returns, so a
+     * step recorded immediately before an exception or crash is present when it is
+     * captured. The work is bounded and cheap, adding negligible latency to the caller.
      *
      * @param message a non-empty description of the step
      * @param properties optional user-supplied properties (the reserved keys

posthog/src/main/java/com/posthog/internal/errortracking/PostHogExceptionStepsBuffer.kt

@@ -29,8 +29,9 @@ internal class PostHogExceptionStepsBuffer(
     private class Entry(val step: Map<String, Any>, val bytes: Int)
 
     /**
-     * Normalizes and appends a step. [timestamp] is captured by the caller (on the
-     * calling thread); this method is expected to run on the SDK's background queue.
+     * Normalizes and appends a step synchronously on the calling thread, so a step
+     * recorded just before a crash is buffered when the crash is captured. [timestamp]
+     * is captured by the caller at call time. Thread-safe via [lock].
      */
     fun add(
         message: String,

posthog/src/test/java/com/posthog/PostHogTest.kt

@@ -3394,9 +3394,6 @@ internal class PostHogTest {
         sut.addExceptionStep("B")
         sut.addExceptionStep("C")
 
-        // drain the queue so the buffered steps are recorded before capture reads them
-        queueExecutor.submit { }.get()
-
         sut.captureException(RuntimeException("boom"))
 
         queueExecutor.shutdownAndAwaitTermination()
@@ -3420,7 +3417,6 @@ internal class PostHogTest {
         val sut = getSut(url.toString(), preloadFeatureFlags = false, reloadFeatureFlags = false)
 
         sut.addExceptionStep("buffered")
-        queueExecutor.submit { }.get()
 
         sut.captureException(
             RuntimeException("boom"),
@@ -3447,13 +3443,11 @@ internal class PostHogTest {
 
         sut.addExceptionStep("A")
         sut.addExceptionStep("B")
-        queueExecutor.submit { }.get()
         sut.captureException(RuntimeException("first"))
 
         sut.reset()
 
         sut.addExceptionStep("C")
-        queueExecutor.submit { }.get()
         sut.captureException(RuntimeException("second"))
 
         // flushAt is high so neither capture triggers a flush on its own; flush explicitly
@@ -3495,7 +3489,6 @@ internal class PostHogTest {
             )
 
         sut.addExceptionStep("A")
-        queueExecutor.submit { }.get()
         sut.captureException(RuntimeException("boom"))
 
         queueExecutor.shutdownAndAwaitTermination()