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
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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

Expand Down
14 changes: 14 additions & 0 deletions tests/test_trace_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down
5 changes: 4 additions & 1 deletion trace_client/trace_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading