From 7c2cc740cb73ad0c27f3d7cb5e06b9704a6381f2 Mon Sep 17 00:00:00 2001 From: Daniel McCoy Stephenson Date: Wed, 28 Oct 2026 05:59:32 -0600 Subject: [PATCH 1/2] Bring the docs up to date with coalescing The class Javadoc still said three properties hold for report() after 0.7.0 added a fourth; the logger Javadoc said only a full queue drops silently, but so does a new event past MAX_COALESCED_EVENTS; the wire format did not mention the coalesced tag; and the counting formula did not say that a count at MAX_TAGS, or on an event with its own coalesced tag, is sent untagged (#31). Also rejoins a line break in close(). Co-Authored-By: Claude Opus 5.5 --- README.md | 7 +++++-- .../software/stephenson/trace/TraceClient.java | 16 ++++++++++------ 2 files changed, 15 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index d3943a4..f53dc9a 100644 --- a/README.md +++ b/README.md @@ -170,7 +170,9 @@ So the number of times something happened is the sum, over stored events, of `value` for events tagged `coalesced` and 1 for the rest — for a valueless event like `command`, simply `SUM(COALESCE(value, 1))`. Counting rows still works for "was it used, by how many servers"; it now undercounts "how many -times", by design. +times", by design. One exception: an event that already carries 32 tags, +or its own `coalesced` tag, has its count sent without the `coalesced` tag +(the server accepts at most 32), so that count reads as a single report. A minute is long enough that a command dispatched every tick is one event a minute instead of 1,200, and short enough that a person trying a command @@ -267,7 +269,8 @@ Shade it into a plugin jar; it is one class. `value` is omitted when not given, and when it is NaN or infinite (neither is JSON); `tags` always holds at least `version`, and -`install` whenever the client has an [installation ID](#every-event-carries-a-random-server-id). The server assigns the +`install` whenever the client has an [installation ID](#every-event-carries-a-random-server-id), and the count of a +[coalesced](#repeated-events-are-coalesced) event also carries `coalesced`. The server assigns the timestamp. A `201` is success; anything else is logged at `FINE` and dropped. Redirects are not followed. The body is streamed with a fixed length, so diff --git a/src/main/java/software/stephenson/trace/TraceClient.java b/src/main/java/software/stephenson/trace/TraceClient.java index b894591..b82abc7 100644 --- a/src/main/java/software/stephenson/trace/TraceClient.java +++ b/src/main/java/software/stephenson/trace/TraceClient.java @@ -40,7 +40,7 @@ * Reports usage events to a trace server, and never gets in the way of the * program doing the reporting. * - *

Three properties hold for every call to {@link #report}: + *

Four properties hold for every call to {@link #report}: * *