From 307ce2c549c66c4dd2e05d77680634dea8b9e85a Mon Sep 17 00:00:00 2001 From: Daniel McCoy Stephenson Date: Fri, 13 Nov 2026 19:48:04 -0700 Subject: [PATCH] Say that reports still queued at close()'s timeout are sent afterwards, not dropped close(timeout) returns once the timeout runs out, but the daemon sender keeps draining what was queued and only stops when it reaches the sentinel. The docstring and README read as if the thread stopped at the timeout. Say what actually happens, mention close(timeout=...) in the README, pin the behaviour with a test, and say the 32-tag cap counts version. Co-Authored-By: Claude Opus 5.5 --- README.md | 4 ++-- tests/test_trace_client.py | 14 ++++++++++++++ trace_client/trace_client.py | 5 ++++- 3 files changed, 20 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 900e1bb..ad97e48 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ trace = TraceClient(url, "roam", __version__, key=key, `install_id=` is trimmed, wins over `install_id_file=`, and over 255 characters raises `ValueError`, like the version. An event that passes its own `install` tag keeps it, and `install` is never added to an event that -already has 32 tags (the server's limit). `trace.install_id` returns the ID +already has 32 tags, `version` included (the server's limit). `trace.install_id` returns the ID in use (`None` when disabled or when there is none), so a program can print it. @@ -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) to be sent before the thread stops, 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. | +| **`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. | ## Turning it off diff --git a/tests/test_trace_client.py b/tests/test_trace_client.py index 2a35693..5b4ce79 100644 --- a/tests/test_trace_client.py +++ b/tests/test_trace_client.py @@ -711,6 +711,20 @@ def test_close_still_returns_within_the_timeout_when_the_server_hangs(self): self.assertLess(time.monotonic() - before, 2.0, "draining must be bounded by the timeout") self.capture.release.set() + def test_reports_still_queued_at_the_timeout_are_sent_after_close_returns(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("seq", tags={"n": "0"}) + client.report("seq", tags={"n": "1"}) + client.close(timeout=0.5) + self.assertTrue(thread.is_alive(), "close() returned on its timeout with the sender still busy") + self.capture.release.set() + thread.join(30) + self.assertFalse(thread.is_alive(), "the sender stops once it reaches what close() queued behind them") + self.assertEqual(["0", "1"], [json.loads(r["body"])["tags"]["n"] for r in self.capture.requests], + "reports queued before close() are not discarded when its timeout runs out") + def test_close_is_prompt_and_idempotent(self): client = TraceClient(self.base_url, "MyGame", "1.2.3", key="k") client.report("startup") diff --git a/trace_client/trace_client.py b/trace_client/trace_client.py index 8854a7e..ce50d65 100644 --- a/trace_client/trace_client.py +++ b/trace_client/trace_client.py @@ -298,7 +298,10 @@ def close(self, timeout: float = TIMEOUT_SECONDS) -> None: and then exits within milliseconds -- a CLI, a short script -- would otherwise lose its one event to the race between queueing it and the sender thread picking it up. The bound still holds: an unreachable - server costs at most ``timeout``, never a hang. Safe to call more than + 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.""" if self._queue is None or self._thread is None: return