diff --git a/README.md b/README.md index d547a74..6d54261 100644 --- a/README.md +++ b/README.md @@ -80,8 +80,10 @@ kept byte for byte. If the file cannot be read or written, a fresh ID is used in memory for that run only — `build()` still never throws. **Resetting it.** Delete the `server-id:` line; the next start writes a new -one. Or set your own value (letters, digits, `_`, `.`, `-`; at most 255 -characters). +one. Or set your own value (letters, digits, `_`, `.`, `-`, starting with a +letter or digit; at most 255 characters). A `server-id:` line whose value is +anything else is ignored, and the next start appends a new one to the end of +the file. **Opting out.** Every [opt-out](#opting-out) below also stops the ID: a disabled client never generates one, never writes one, and sends nothing. @@ -223,7 +225,8 @@ Shade it into a plugin jar; it is one class. {"application":"MyPlugin","name":"command","value":1.0,"tags":{"name":"home","version":"1.4.0","install":"0f8b6c1e-3a52-4c8e-9a0d-6e2f1b7c4d90"}} ``` -`value` is omitted when not given; `tags` always holds at least `version`, and +`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 timestamp. A `201` is success; anything else is logged at `FINE` and dropped. diff --git a/src/main/java/software/stephenson/trace/TraceClient.java b/src/main/java/software/stephenson/trace/TraceClient.java index fd71ff0..02ab1c3 100644 --- a/src/main/java/software/stephenson/trace/TraceClient.java +++ b/src/main/java/software/stephenson/trace/TraceClient.java @@ -488,9 +488,10 @@ private ServerWideConfig readServerWideConfig(File pluginsDirectory) { * double- or single-quoted. Entries the trace server would reject -- and * anything this reader does not understand -- are dropped, one by one, * and at most {@link #MAX_TAGS} are kept. The first {@code server-id:} - * line at column 0, outside a {@code tags:} block, whose value is a valid - * tag value made of {@code [A-Za-z0-9_.-]} is the installation's ID; any - * other is ignored. Nothing here throws. + * line at column 0, outside a {@code tags:} block, whose value is at most + * {@value #MAX_TAG_LENGTH} characters of {@code [A-Za-z0-9_.-]} starting + * with a letter or digit is the installation's ID; any other is ignored. + * Nothing here throws. */ static ServerWideConfig parseServerWideConfig(List lines) { Boolean disables = null; @@ -703,7 +704,8 @@ public void report(String name) { /** * Reports that {@code name} happened, with an optional numeric value and - * optional string tags. Returns immediately; see the class comment. + * optional string tags. Returns immediately; see the class comment. A + * {@code null} or blank name sends nothing. */ public void report(String name, Double value, Map tags) { if (executor == null || name == null || name.trim().isEmpty()) { diff --git a/src/test/java/software/stephenson/trace/TraceClientTest.java b/src/test/java/software/stephenson/trace/TraceClientTest.java index ae7ec75..88f837c 100644 --- a/src/test/java/software/stephenson/trace/TraceClientTest.java +++ b/src/test/java/software/stephenson/trace/TraceClientTest.java @@ -1183,6 +1183,14 @@ void installId_anExistingServerIdIsUsedAndAnUnusableOneIsIgnored() { assertEquals("abc-123", TraceClient.parseServerWideConfig(Arrays.asList("server-id: \"abc-123\" # mine")).serverId); assertEquals("first", TraceClient.parseServerWideConfig(Arrays.asList("server-id: first", "server-id: second")).serverId); assertEquals("good", TraceClient.parseServerWideConfig(Arrays.asList("server-id:", "server-id: has space", "server-id: good")).serverId); + assertNull(TraceClient.parseServerWideConfig(Arrays.asList("server-id: _mine")).serverId, "starts with a letter or digit"); + assertEquals("good", TraceClient.parseServerWideConfig(Arrays.asList("server-id: -mine", "server-id: good")).serverId); + StringBuilder overlong = new StringBuilder(); + for (int i = 0; i <= TraceClient.MAX_TAG_LENGTH; i++) { + overlong.append('a'); + } + assertNull(TraceClient.parseServerWideConfig(Arrays.asList("server-id: " + overlong)).serverId, + "at most MAX_TAG_LENGTH characters"); assertNull(TraceClient.parseServerWideConfig(Arrays.asList(" server-id: indented")).serverId, "column 0 only"); assertNull(TraceClient.parseServerWideConfig(Arrays.asList("# server-id: commented")).serverId); TraceClient.ServerWideConfig inTags = TraceClient.parseServerWideConfig(Arrays.asList("tags:", " server-id: x"));