From 7e404c0951dc0ba6b4b51927fbe5e3f27e4913f8 Mon Sep 17 00:00:00 2001 From: Daniel McCoy Stephenson Date: Sat, 24 Oct 2026 01:55:04 -0600 Subject: [PATCH 1/3] Document what the wire format drops: NaN/infinite values, None tags and blank names Co-Authored-By: Claude Opus 5.5 --- README.md | 7 +++++-- trace_client/trace_client.py | 4 +++- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4437196..1ed08f1 100644 --- a/README.md +++ b/README.md @@ -148,8 +148,11 @@ There is no PyPI package yet; the file is the distribution. {"application":"roam","name":"command","value":1.0,"tags":{"name":"home","version":"1.4.0"}} ``` -`value` is omitted when not given; `tags` always holds at least `version`, and -`install` when the client has an [installation ID](#every-event-carries-a-random-installation-id). The server assigns the +`value` is omitted when not given, and when it is NaN or infinite (JSON has no +such numbers); `tags` always holds at least `version`, and +`install` when the client has an [installation ID](#every-event-carries-a-random-installation-id). A tag whose +key or value is `None` is left out, and every other key and value is sent as a +string. An event with a blank `name` is not sent at all. The server assigns the timestamp. A `201` is success; anything else is logged at `DEBUG` and dropped. ## Keys diff --git a/trace_client/trace_client.py b/trace_client/trace_client.py index 3515ac2..7dab6cc 100644 --- a/trace_client/trace_client.py +++ b/trace_client/trace_client.py @@ -244,7 +244,9 @@ def enabled(self) -> bool: def report(self, name: str, value: Optional[float] = None, tags: Optional[Mapping[str, str]] = None) -> None: """Report that ``name`` happened, with an optional numeric value and - optional string tags. Returns immediately; see the class docstring.""" + optional string tags. Returns immediately; see the class docstring. + A blank ``name`` is dropped; so is a NaN or infinite ``value``, and + any tag whose key or value is ``None``.""" if self._queue is None: return try: From 1aae4f000b0af7f0f1dc031043c7a3817ec444c3 Mon Sep 17 00:00:00 2001 From: Daniel McCoy Stephenson Date: Sat, 24 Oct 2026 01:56:17 -0600 Subject: [PATCH 2/3] Say the report() docstring leaves a bad value out of the event, not the event out Co-Authored-By: Claude Opus 5.5 --- trace_client/trace_client.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/trace_client/trace_client.py b/trace_client/trace_client.py index 7dab6cc..6f08222 100644 --- a/trace_client/trace_client.py +++ b/trace_client/trace_client.py @@ -245,8 +245,8 @@ def report(self, name: str, value: Optional[float] = None, tags: Optional[Mapping[str, str]] = None) -> None: """Report that ``name`` happened, with an optional numeric value and optional string tags. Returns immediately; see the class docstring. - A blank ``name`` is dropped; so is a NaN or infinite ``value``, and - any tag whose key or value is ``None``.""" + A blank ``name`` sends nothing. A NaN or infinite ``value``, and any + tag whose key or value is ``None``, is left out of the event.""" if self._queue is None: return try: From 999871a92adb5bda4002fbde7ec13fa8ad629041 Mon Sep 17 00:00:00 2001 From: Daniel McCoy Stephenson Date: Sat, 24 Oct 2026 01:57:12 -0600 Subject: [PATCH 3/3] Re-run CI on the docstring rewording Co-Authored-By: Claude Opus 5.5