diff --git a/README.md b/README.md index ad97e48..a3a8287 100644 --- a/README.md +++ b/README.md @@ -112,7 +112,7 @@ sends nothing. | **Returns immediately** | The HTTP call runs on one daemon thread the client owns. A game loop can report from its main thread and no frame waits on the network. | | **Never raises** | A server that is down, slow, or rejecting the key is a dropped report, not an exception in your program. Drops are logged at `DEBUG` on the `trace` logger, otherwise not at all. | | **Bounded** | At most 256 reports wait to be sent; past that, new ones are dropped. A trace server that is unreachable for a week costs a few kilobytes, not your memory. | -| **`close()` drains** | Reports already queued get up to the client timeout (5 s total, or `close(timeout=...)`) to be sent before `close()` returns, so a CLI that reports and exits at once does not lose its event. Still bounded: an unreachable server delays exit by at most the timeout. Reports still queued when the timeout runs out are not discarded: the daemon thread keeps sending them after `close()` returns, then stops; whatever it has not sent when the program exits is lost. | +| **`close()` drains** | Reports already queued get up to the client timeout (5 s total, or `close(timeout=...)`) to be sent before `close()` returns, so a CLI that reports and exits at once does not lose its event. Still bounded: an unreachable server delays exit by at most the timeout. Reports still queued when the timeout runs out are not discarded: the daemon thread keeps sending them after `close()` returns, then stops; whatever it has not sent when the program exits is lost. On a full queue, `close()` drops the oldest queued report (logged at `DEBUG`) to make room for the signal that stops the thread. | ## Turning it off diff --git a/tests/test_trace_client.py b/tests/test_trace_client.py index 5b4ce79..1c72743 100644 --- a/tests/test_trace_client.py +++ b/tests/test_trace_client.py @@ -764,6 +764,28 @@ def test_close_on_a_full_queue_drops_the_oldest_report_and_still_stops_the_sende self.assertIn("0", sent) self.assertIn(str(TraceClient.QUEUE_CAPACITY), sent) + def test_the_report_close_drops_from_a_full_queue_is_logged_at_debug(self): + self.capture.release.clear() # hold the sender on the first report + client = TraceClient(self.base_url, "MyGame", "1.2.3", key="k") + thread = client._thread + client.report("in-flight") + deadline = time.monotonic() + 5 + while time.monotonic() < deadline and not client._queue.empty(): + time.sleep(0.01) # until the sender has taken it and is waiting on the server + self.assertTrue(client._queue.empty(), "the sender should have picked up the first report") + client.report("oldest-queued") + for _ in range(TraceClient.QUEUE_CAPACITY - 1): + client.report("filler") + client.close(timeout=0.5) + dropped = [r for r in self.log if r.getMessage().startswith("[trace] queue full at close, dropped ")] + self.assertEqual(1, len(dropped), + "the report close() displaces is logged, like every other drop: %r" + % [r.getMessage() for r in self.log]) + self.assertIn("oldest-queued", dropped[0].getMessage(), "the log names the report it dropped") + self.assertEqual(logging.DEBUG, dropped[0].levelno, "drops are logged at DEBUG only") + self.capture.release.set() + thread.join(30) + # -- the per-installation ID ------------------------------------------ def _tmpdir(self): diff --git a/trace_client/trace_client.py b/trace_client/trace_client.py index ce50d65..884093e 100644 --- a/trace_client/trace_client.py +++ b/trace_client/trace_client.py @@ -301,8 +301,10 @@ def close(self, timeout: float = TIMEOUT_SECONDS) -> None: server costs at most ``timeout``, never a hang. Reports still queued when ``timeout`` runs out are not discarded: the daemon thread keeps sending them after ``close()`` returns, then stops, and whatever it - has not sent when the program exits is lost. Safe to call more than - once, and on a disabled client.""" + has not sent when the program exits is lost. On a full queue the + oldest queued report is dropped (logged at DEBUG) to make room for + the signal that stops the thread. Safe to call more than once, and + on a disabled client.""" if self._queue is None or self._thread is None: return q, thread = self._queue, self._thread @@ -314,7 +316,8 @@ def close(self, timeout: float = TIMEOUT_SECONDS) -> None: # the 257th. Drop the oldest to make room -- one lost report beats a # thread that never stops. try: - q.get_nowait() + dropped = q.get_nowait() + _LOG.debug("[trace] queue full at close, dropped %s", dropped) q.put_nowait(None) except (queue.Empty, queue.Full): pass