From 22b5ce43e5bdb77910913286e2679c27f395cac0 Mon Sep 17 00:00:00 2001 From: Daniel McCoy Stephenson Date: Mon, 19 Oct 2026 03:40:15 -0600 Subject: [PATCH 1/2] Say what the logger hears and that queue drops are silent, in the Javadoc Builder.logger said "Where dropped reports are mentioned", but a report dropped by the full queue goes through DiscardPolicy and is never logged, as the README's "Bounded" row has said since #20. The logger also hears more than drops: build() logs a server-wide config or install ID file it could not read or write. The Javadoc now lists what is logged and what is not. The class Javadoc's "It is bounded" bullet now says the drop is silent, matching the same README row. Co-Authored-By: Claude Opus 5.5 --- .../java/software/stephenson/trace/TraceClient.java | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/src/main/java/software/stephenson/trace/TraceClient.java b/src/main/java/software/stephenson/trace/TraceClient.java index 02ab1c3..bcbeec2 100644 --- a/src/main/java/software/stephenson/trace/TraceClient.java +++ b/src/main/java/software/stephenson/trace/TraceClient.java @@ -48,8 +48,8 @@ * are logged at {@link Level#FINE} if a logger was given, and otherwise * not at all. *
  • It is bounded. At most {@value #QUEUE_CAPACITY} reports wait to - * be sent; beyond that, new reports are dropped rather than accumulated. - * A trace server that is unreachable for a week costs a few kilobytes, + * be sent; beyond that, new reports are dropped rather than accumulated, + * without a log line, even at {@link Level#FINE}. A trace server that is unreachable for a week costs a few kilobytes, * not the host's heap.
    • * * @@ -958,7 +958,14 @@ public Builder installIdFile(File installIdFile) { return this; } - /** Where dropped reports are mentioned, at {@link Level#FINE}. Optional. */ + /** + * Where problems are mentioned, at {@link Level#FINE}, prefixed + * {@code [trace]}: a report the server did not answer {@code 201} + * to or that could not be delivered, and a server-wide config or + * install ID file that could not be read or written in + * {@link #build()}. A report dropped because the queue is full is + * not mentioned. Optional; without one, nothing is logged. + */ public Builder logger(Logger logger) { this.logger = logger; return this; From 6aaeff9faadfd241229b8dc6dfdf9f20bc050fbb Mon Sep 17 00:00:00 2001 From: Daniel McCoy Stephenson Date: Mon, 19 Oct 2026 03:40:58 -0600 Subject: [PATCH 2/2] Rewrap the bounded bullet in the class Javadoc Co-Authored-By: Claude Opus 5.5 --- src/main/java/software/stephenson/trace/TraceClient.java | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/main/java/software/stephenson/trace/TraceClient.java b/src/main/java/software/stephenson/trace/TraceClient.java index bcbeec2..c83a2b9 100644 --- a/src/main/java/software/stephenson/trace/TraceClient.java +++ b/src/main/java/software/stephenson/trace/TraceClient.java @@ -49,8 +49,9 @@ * not at all. *
  • It is bounded. At most {@value #QUEUE_CAPACITY} reports wait to * be sent; beyond that, new reports are dropped rather than accumulated, - * without a log line, even at {@link Level#FINE}. A trace server that is unreachable for a week costs a few kilobytes, - * not the host's heap.
    • + * without a log line, even at {@link Level#FINE}. A trace server + * that is unreachable for a week costs a few kilobytes, not the + * host's heap. * * *

    Reporting is opt-out, and the person running the program always has the