Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
22 changes: 22 additions & 0 deletions tests/test_trace_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
9 changes: 6 additions & 3 deletions trace_client/trace_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
Loading