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