From 8f0adbcf1a051861c58b3e1593acd0483bab9287 Mon Sep 17 00:00:00 2001 From: Daniel McCoy Stephenson Date: Sun, 18 Oct 2026 03:09:40 -0600 Subject: [PATCH] Say that queue drops are silent and how the tags block skips lines The "Bounded" row sat under "Drops are logged at FINE", but a report dropped by a full queue goes through DiscardPolicy and is never logged. The row now says so, and the flood test attaches a logger and checks nothing is logged. The server-wide tags bullets now also say that a line indented differently from the block's first entry is skipped, and that an enabled: line inside the block is a tag rather than the switch. Both were already in parseServerWideConfig's Javadoc and its tests. Co-Authored-By: Claude Opus 5.5 --- README.md | 8 +++++--- .../java/software/stephenson/trace/TraceClientTest.java | 9 ++++++++- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 6d54261..bd5f48e 100644 --- a/README.md +++ b/README.md @@ -137,7 +137,7 @@ generates, reads or writes an ID. |---|---| | **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. | -| **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 heap. | +| **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. | | **`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. | ## Opting out @@ -175,8 +175,10 @@ tags: - `tags:` starts at column 0 and is followed by indented `key: value` lines. Values may be double-quoted, single-quoted or bare; blank lines and `#` - comments inside the block are skipped. The block ends at the next line that - is not indented, or at the end of the file. + comments inside the block are skipped, and so is any line indented + differently from the block's first entry. The block ends at the next line + that is not indented, or at the end of the file. An `enabled:` line inside + the block is a tag like any other, not the switch. - An event's own tag always wins, and the program's version is the event's own: a server-wide `version` never overwrites it. - Entries the trace server would reject are dropped one by one, never the diff --git a/src/test/java/software/stephenson/trace/TraceClientTest.java b/src/test/java/software/stephenson/trace/TraceClientTest.java index c678ed7..f990f2c 100644 --- a/src/test/java/software/stephenson/trace/TraceClientTest.java +++ b/src/test/java/software/stephenson/trace/TraceClientTest.java @@ -483,8 +483,12 @@ void queue_isBoundedAndDropsRatherThanGrows() throws Exception { exchange.close(); }); slow.start(); + RecordingHandler log = new RecordingHandler(); + Logger logger = Logger.getLogger("TraceClientTest.flood"); + logger.setLevel(Level.ALL); + logger.addHandler(log); TraceClient client = TraceClient.builder("http://127.0.0.1:" + slow.getAddress().getPort(), "MyPlugin", "1.2.3") - .key("k").build(); + .key("k").logger(logger).build(); int flood = TraceClient.QUEUE_CAPACITY * 3; // Act @@ -509,6 +513,9 @@ void queue_isBoundedAndDropsRatherThanGrows() throws Exception { "delivered " + delivered.get() + " of " + flood + "; at most the in-flight one plus a full queue may survive"); assertTrue(delivered.get() < flood, "an unbounded queue would have delivered all " + flood); client.close(); + // Every delivered report was a 201, so any log line would be about a + // dropped one; the README says those drops are silent. + assertTrue(log.records.isEmpty(), "a full queue drops without logging, but logged: " + log.records.size()); slow.stop(0); }