From 2a42b13d0a53b3b9762aa067bdf8fa9d53a048fa Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Fri, 20 Nov 2026 09:26:09 +0100 Subject: [PATCH 1/3] fix: attach $sdk_debug_pending_queue_size only once the queue reaches flushAt --- .changeset/quiet-queues-rest.md | 6 ++++ .../PostHogAndroidEventSnapshotsTest.kt | 7 ++--- .../json/snapshots/batch-request.json | 5 --- posthog/api/posthog.api | 3 ++ posthog/src/main/java/com/posthog/PostHog.kt | 4 ++- .../java/com/posthog/internal/PostHogQueue.kt | 3 ++ .../posthog/internal/PostHogQueueInterface.kt | 7 +++++ .../src/test/java/com/posthog/PostHogTest.kt | 31 ++++++++++++++----- .../com/posthog/internal/PostHogQueueTest.kt | 25 +++++++++++++++ 9 files changed, 72 insertions(+), 19 deletions(-) create mode 100644 .changeset/quiet-queues-rest.md diff --git a/.changeset/quiet-queues-rest.md b/.changeset/quiet-queues-rest.md new file mode 100644 index 000000000..2b96c0e17 --- /dev/null +++ b/.changeset/quiet-queues-rest.md @@ -0,0 +1,6 @@ +--- +"posthog": patch +"posthog-android": patch +--- + +Only attach `$sdk_debug_pending_queue_size` once the event queue reaches `flushAt`, so healthy queues no longer add it to every event diff --git a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt index e59c0977c..2e5979a5c 100644 --- a/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt +++ b/posthog-android/src/test/java/com/posthog/android/PostHogAndroidEventSnapshotsTest.kt @@ -30,6 +30,7 @@ import kotlin.test.AfterTest import kotlin.test.BeforeTest import kotlin.test.Test import kotlin.test.assertEquals +import kotlin.test.assertFalse import kotlin.test.assertIs import kotlin.test.assertNotNull import kotlin.test.assertTrue @@ -258,11 +259,7 @@ internal class PostHogAndroidEventSnapshotsTest { event["uuid"] = "" val properties = event.map("properties") normalizeSdkVersion(properties) - // Depends on how many earlier captures the async queueExecutor has drained by the time - // this event's properties are built on the calling thread -- not deterministic run to run. - if (properties.containsKey("\$sdk_debug_pending_queue_size")) { - properties["\$sdk_debug_pending_queue_size"] = "" - } + assertFalse(properties.containsKey("\$sdk_debug_pending_queue_size")) } val featureFlagEvent = batch.single { (it as Map<*, *>)["event"] == "\$feature_flag_called" } as Map<*, *> diff --git a/posthog-android/src/test/resources/json/snapshots/batch-request.json b/posthog-android/src/test/resources/json/snapshots/batch-request.json index c9d3b3997..5ec5dc8a4 100644 --- a/posthog-android/src/test/resources/json/snapshots/batch-request.json +++ b/posthog-android/src/test/resources/json/snapshots/batch-request.json @@ -54,7 +54,6 @@ ], "$is_identified": false, "$process_person_profile": true, - "$sdk_debug_pending_queue_size": "", "$recording_status": "disabled", "$sdk_debug_replay_event_trigger_status": "trigger_disabled", "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", @@ -100,7 +99,6 @@ "$anon_distinct_id": "anonymous-user", "$is_identified": true, "$process_person_profile": true, - "$sdk_debug_pending_queue_size": "", "$recording_status": "disabled", "$sdk_debug_replay_event_trigger_status": "trigger_disabled", "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", @@ -144,7 +142,6 @@ }, "$is_identified": true, "$process_person_profile": true, - "$sdk_debug_pending_queue_size": "", "$recording_status": "disabled", "$sdk_debug_replay_event_trigger_status": "trigger_disabled", "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", @@ -193,7 +190,6 @@ "$feature_flag_reason": "", "$is_identified": true, "$process_person_profile": true, - "$sdk_debug_pending_queue_size": "", "$recording_status": "disabled", "$sdk_debug_replay_event_trigger_status": "trigger_disabled", "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", @@ -294,7 +290,6 @@ "component": "checkout", "$is_identified": true, "$process_person_profile": true, - "$sdk_debug_pending_queue_size": "", "$recording_status": "disabled", "$sdk_debug_replay_event_trigger_status": "trigger_disabled", "$sdk_debug_replay_linked_flag_trigger_status": "trigger_disabled", diff --git a/posthog/api/posthog.api b/posthog/api/posthog.api index e2deac678..027a4049b 100644 --- a/posthog/api/posthog.api +++ b/posthog/api/posthog.api @@ -1036,6 +1036,7 @@ public final class com/posthog/internal/PostHogQueue : com/posthog/internal/Post public fun add (Ljava/lang/Object;)V public fun clear ()V public fun flush ()V + public fun getBackedUpSize ()Ljava/lang/Integer; public final fun getQueueDirectory ()Ljava/io/File; public fun getSize ()I public final fun reloadFromDisk ()V @@ -1048,6 +1049,7 @@ public abstract interface class com/posthog/internal/PostHogQueueInterface { public abstract fun clear ()V public abstract fun flush ()V public fun flushForShutdown ()V + public fun getBackedUpSize ()Ljava/lang/Integer; public abstract fun getSize ()I public abstract fun start ()V public abstract fun stop ()V @@ -1055,6 +1057,7 @@ public abstract interface class com/posthog/internal/PostHogQueueInterface { public final class com/posthog/internal/PostHogQueueInterface$DefaultImpls { public static fun flushForShutdown (Lcom/posthog/internal/PostHogQueueInterface;)V + public static fun getBackedUpSize (Lcom/posthog/internal/PostHogQueueInterface;)Ljava/lang/Integer; } public final class com/posthog/internal/PostHogRemoteConfig : com/posthog/internal/PostHogFeatureFlagsInterface { diff --git a/posthog/src/main/java/com/posthog/PostHog.kt b/posthog/src/main/java/com/posthog/PostHog.kt index dd7a1dbe3..29ab0dbf9 100644 --- a/posthog/src/main/java/com/posthog/PostHog.kt +++ b/posthog/src/main/java/com/posthog/PostHog.kt @@ -846,6 +846,8 @@ public class PostHog private constructor( // extend(properties, sdkDebugProperties). After session resolution so the debug snapshot // never precedes a rotation triggered by getActiveSessionId() above. if (appendSharedProps) { + // SDK-owned: a registered or caller value must not make a healthy queue look backed up. + props.remove("\$sdk_debug_pending_queue_size") props.putAll(sdkDebugProperties(sessionIdString, timestamp, claimReplayDebugBundle)) } @@ -889,7 +891,7 @@ public class PostHog private constructor( if (claimed) { sessionStart(sessionId, managerStart)?.let { props["\$sdk_debug_session_start"] = it } } - queue?.size?.let { props["\$sdk_debug_pending_queue_size"] = it } + queue?.backedUpSize?.let { props["\$sdk_debug_pending_queue_size"] = it } } catch (e: Throwable) { props["\$sdk_debug_error_capturing_properties"] = e.toString().take(MAX_DEBUG_ERROR_LENGTH) } diff --git a/posthog/src/main/java/com/posthog/internal/PostHogQueue.kt b/posthog/src/main/java/com/posthog/internal/PostHogQueue.kt index 8b07352c2..7302d398c 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogQueue.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogQueue.kt @@ -54,6 +54,9 @@ public class PostHogQueue( override val size: Int get() = synchronized(dequeLock) { deque.size } + override val backedUpSize: Int? + get() = size.takeIf { it > 0 && it >= batchLimits.flushAt } + public val queueDirectory: File? get() = spec.storagePrefix?.let { File(it, config.projectToken) } diff --git a/posthog/src/main/java/com/posthog/internal/PostHogQueueInterface.kt b/posthog/src/main/java/com/posthog/internal/PostHogQueueInterface.kt index 8b3ece53d..1824dbe59 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogQueueInterface.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogQueueInterface.kt @@ -14,6 +14,13 @@ import com.posthog.PostHogInternal public interface PostHogQueueInterface { public val size: Int + /** + * The size once the queue has reached its flush threshold, else null: below it the queue is + * ordinary batching, not a backlog worth reporting. + */ + public val backedUpSize: Int? + get() = null + public fun add(record: Record) public fun flush() diff --git a/posthog/src/test/java/com/posthog/PostHogTest.kt b/posthog/src/test/java/com/posthog/PostHogTest.kt index fd2904b54..7d1429c9b 100644 --- a/posthog/src/test/java/com/posthog/PostHogTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogTest.kt @@ -999,7 +999,7 @@ internal class PostHogTest { assertTrue(theEvent.properties!!.containsKey("\$active_feature_flags")) assertEquals("disabled", theEvent.properties!!["\$recording_status"]) assertFalse(theEvent.properties!!.containsKey("\$sdk_debug_session_start")) - assertNotNull(theEvent.properties!!["\$sdk_debug_pending_queue_size"]) + assertFalse(theEvent.properties!!.containsKey("\$sdk_debug_pending_queue_size")) sut.close() } @@ -3890,7 +3890,7 @@ internal class PostHogTest { assertEquals("trigger_pending", props["\$sdk_debug_replay_event_trigger_status"]) assertEquals("trigger_disabled", props["\$sdk_debug_replay_linked_flag_trigger_status"]) assertEquals(1, (props["\$sdk_debug_replay_internal_buffer_length"] as Number).toInt()) - assertNotNull(props["\$sdk_debug_pending_queue_size"]) + assertFalse(props.containsKey("\$sdk_debug_pending_queue_size")) assertFalse(props.containsKey("\$sdk_debug_replay_capture_mode")) assertFalse(props.containsKey("\$sdk_debug_replay_flush_hold_reason")) assertFalse(props.containsKey("\$sdk_debug_replay_pending_trigger_conditions")) @@ -3926,7 +3926,7 @@ internal class PostHogTest { assertEquals("disabled", theEvent.properties!!["\$recording_status"]) assertEquals("wireframe", theEvent.properties!!["\$sdk_debug_replay_capture_mode"]) assertNotNull(theEvent.properties!!["\$sdk_debug_session_start"]) - assertNotNull(theEvent.properties!!["\$sdk_debug_pending_queue_size"]) + assertFalse(theEvent.properties!!.containsKey("\$sdk_debug_pending_queue_size")) assertFalse(theEvent.properties!!.containsKey("\$sdk_debug_replay_throttle_delay_ms")) assertFalse(theEvent.properties!!.containsKey("\$sdk_debug_current_session_duration")) @@ -3994,7 +3994,7 @@ internal class PostHogTest { val sut = getSut(url.toString(), preloadFeatureFlags = false, reloadFeatureFlags = false, integration = integration) sut.register("\$recording_status", "registered") - sut.capture(EVENT, properties = mapOf("\$recording_status" to "caller", "\$sdk_debug_pending_queue_size" to -1)) + sut.capture(EVENT, properties = mapOf("\$recording_status" to "caller")) queueExecutor.shutdownAndAwaitTermination() @@ -4004,7 +4004,6 @@ internal class PostHogTest { val theEvent = batch.batch.first() assertEquals("active", theEvent.properties!!["\$recording_status"]) - assertNotEquals(-1, (theEvent.properties!!["\$sdk_debug_pending_queue_size"] as Number).toInt()) sut.close() } @@ -4063,7 +4062,7 @@ internal class PostHogTest { assertFalse(theEvent.properties!!.containsKey("\$recording_status")) // The session and queue keys do not come from the replay handler, so they survive its throw. assertNotNull(theEvent.properties!!["\$sdk_debug_session_start"]) - assertNotNull(theEvent.properties!!["\$sdk_debug_pending_queue_size"]) + assertFalse(theEvent.properties!!.containsKey("\$sdk_debug_pending_queue_size")) sut.close() } @@ -4104,6 +4103,22 @@ internal class PostHogTest { beforeSend = beforeSend, ) + @Test + fun `pending queue size is attached only once the queue reaches flushAt`() { + val http = mockHttp() + val sut = getSut(http.url("/").toString(), flushAt = 3, preloadFeatureFlags = false, reloadFeatureFlags = false) + sut.register("\$sdk_debug_pending_queue_size", -1) + + sut.capture(EVENT, properties = mapOf("\$sdk_debug_pending_queue_size" to -2)) + sut.capture(EVENT) + sut.capture(EVENT) + + val events = capturedEvents(http) + assertEquals(listOf(false, false, false), events.map { it.properties!!.containsKey("\$sdk_debug_pending_queue_size") }) + + sut.close() + } + @Test fun `replay debug bundle is attached at most once every 30 seconds while required keys stay on every event`() { val http = mockHttp() @@ -4124,7 +4139,7 @@ internal class PostHogTest { assertEquals("trigger_pending", it.properties!!["\$sdk_debug_replay_event_trigger_status"]) assertEquals("trigger_disabled", it.properties!!["\$sdk_debug_replay_linked_flag_trigger_status"]) assertNotNull(it.properties!!["\$sdk_debug_replay_internal_buffer_length"]) - assertNotNull(it.properties!!["\$sdk_debug_pending_queue_size"]) + assertFalse(it.properties!!.containsKey("\$sdk_debug_pending_queue_size")) } sut.close() @@ -4182,7 +4197,7 @@ internal class PostHogTest { assertEquals(listOf(false, false, true), events.map { it.carriesReplayDebugBundle }) events.forEach { assertEquals("buffering", it.properties!!["\$recording_status"]) - assertNotNull(it.properties!!["\$sdk_debug_pending_queue_size"]) + assertFalse(it.properties!!.containsKey("\$sdk_debug_pending_queue_size")) } sut.close() diff --git a/posthog/src/test/java/com/posthog/internal/PostHogQueueTest.kt b/posthog/src/test/java/com/posthog/internal/PostHogQueueTest.kt index 35b447160..8197a0dd7 100644 --- a/posthog/src/test/java/com/posthog/internal/PostHogQueueTest.kt +++ b/posthog/src/test/java/com/posthog/internal/PostHogQueueTest.kt @@ -31,6 +31,7 @@ import kotlin.test.AfterTest import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertNotNull +import kotlin.test.assertNull import kotlin.test.assertTrue internal class PostHogQueueTest { @@ -221,6 +222,30 @@ internal class PostHogQueueTest { assertEquals(0, http.requestCount) } + @Test + fun `reports a backed-up size only once the queue reaches flushAt`() { + val http = mockHttp() + val sut = + getSut( + host = http.url("/").toString(), + flushAt = 2, + networkStatus = + object : PostHogNetworkStatus { + override fun isConnected() = false + }, + ) + + assertNull(sut.backedUpSize) + + sut.add(generateEvent()) + awaitQueue() + assertNull(sut.backedUpSize) + + sut.add(generateEvent()) + awaitQueue() + assertEquals(2, sut.backedUpSize) + } + @Test fun `does not flush if not connected but try to flush again`() { val http = mockHttp() From 4edcf1d66d3e9f6e914ec9027511bf51fa522e83 Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Fri, 20 Nov 2026 09:29:53 +0100 Subject: [PATCH 2/3] test: cover the queue size reaching an event once the queue backs up --- .../src/test/java/com/posthog/PostHogTest.kt | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/posthog/src/test/java/com/posthog/PostHogTest.kt b/posthog/src/test/java/com/posthog/PostHogTest.kt index 7d1429c9b..bd3623e76 100644 --- a/posthog/src/test/java/com/posthog/PostHogTest.kt +++ b/posthog/src/test/java/com/posthog/PostHogTest.kt @@ -4119,6 +4119,29 @@ internal class PostHogTest { sut.close() } + @Test + fun `a backed-up queue reports its size on the next event`() { + val http = mockHttp() + val sut = getSut(http.url("/").toString(), flushAt = 3, preloadFeatureFlags = false, reloadFeatureFlags = false) + var connected = false + config.networkStatus = + object : PostHogNetworkStatus { + override fun isConnected(): Boolean = connected + } + + repeat(3) { sut.capture(EVENT) } + queueExecutor.awaitExecution() + assertEquals(0, http.requestCount) + sut.capture(EVENT) + + connected = true + sut.flush() + val events = capturedEvents(http) + assertEquals(listOf(null, null, null, 3), events.map { it.properties!!["\$sdk_debug_pending_queue_size"] }) + + sut.close() + } + @Test fun `replay debug bundle is attached at most once every 30 seconds while required keys stay on every event`() { val http = mockHttp() From 0592599f61f731ec5a4e792a4ce419fce2fe6878 Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Fri, 20 Nov 2026 10:46:51 +0100 Subject: [PATCH 3/3] fix: publish the halved flushAt to capture threads --- posthog/src/main/java/com/posthog/internal/PostHogQueue.kt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/posthog/src/main/java/com/posthog/internal/PostHogQueue.kt b/posthog/src/main/java/com/posthog/internal/PostHogQueue.kt index 7302d398c..67da0a516 100644 --- a/posthog/src/main/java/com/posthog/internal/PostHogQueue.kt +++ b/posthog/src/main/java/com/posthog/internal/PostHogQueue.kt @@ -516,7 +516,8 @@ public class PostHogQueue( internal class BatchLimits( var cap: Int, - var flushAt: Int, + // Halved on the queue executor and read on capture threads by backedUpSize. + @Volatile var flushAt: Int, ) { fun halve(actualBatchSize: Int) { cap =