From f7b4307be87ec88e219719e65fabc9db93a344bc Mon Sep 17 00:00:00 2001 From: Daniel McCoy Stephenson Date: Fri, 30 Oct 2026 01:26:41 -0600 Subject: [PATCH] Say that an environment opt-out skips the server-wide file The serverWideConfig Javadoc said build() always makes sure plugins/trace/config.yml exists, but the constructor never reads or creates it once TRACE_USAGE_REPORTING or DO_NOT_TRACK has opted out. readServerWideConfig's Javadoc also left out the server-id: line it reads. The README's "Never throws" row said every drop is logged, which contradicts the "Bounded" row next to it. Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- src/main/java/software/stephenson/trace/TraceClient.java | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f53dc9a..20d36a1 100644 --- a/README.md +++ b/README.md @@ -136,7 +136,7 @@ generates, reads or writes an ID. | Property | Meaning | |---|---| | **Returns immediately** | The HTTP call runs on one daemon thread the client owns. A Spigot plugin can report from the server thread and no tick waits on the network. | -| **Never throws** | A server that is down, slow, or rejecting the key is a dropped report, not an exception in your program. Drops are logged at `FINE` if you gave a logger, otherwise not at all. | +| **Never throws** | A server that is down, slow, or rejecting the key is a dropped report, not an exception in your program. Such a failure is logged at `FINE` if you gave a logger, otherwise not at all. | | **Bounded** | At most 256 reports wait to be sent; past that, new ones are dropped without a log line, even at `FINE`. A trace server that is unreachable for a week costs a few kilobytes, not your heap. | | **Throttled** | Repeats of one event within a minute are counted, not sent: the first goes out at once, the rest as one event when the minute is up. See [below](#repeated-events-are-coalesced). | | **`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. | diff --git a/src/main/java/software/stephenson/trace/TraceClient.java b/src/main/java/software/stephenson/trace/TraceClient.java index f9967cc..8d7a177 100644 --- a/src/main/java/software/stephenson/trace/TraceClient.java +++ b/src/main/java/software/stephenson/trace/TraceClient.java @@ -504,7 +504,8 @@ ServerWideConfig readFromDisk(boolean created) { /** * Ensures {@code /trace/config.yml} exists and reads its - * {@code enabled:} line and {@code tags:} block. No YAML library: the file + * {@code enabled:} line, {@code tags:} block and {@code server-id:} line. + * Not called when the environment opts out. No YAML library: the file * is ours, shallow, and a line scan is enough. Anything going wrong on * disk is logged at FINE and counts as enabled with no tags -- a * read-only plugins directory must not silently switch reporting off, @@ -1123,8 +1124,9 @@ public Builder enabled(boolean enabled) { * server-id: 0f8b6c1e-... * * - *

Both are read once, here. Optional; programs that are not - * plugins leave it unset. + *

All three are read once, here. When an environment variable has + * already turned reporting off, the file is neither read nor created. + * Optional; programs that are not plugins leave it unset. */ public Builder serverWideConfig(File pluginsDirectory) { this.pluginsDirectory = pluginsDirectory;