Skip to content

Commit 628bde2

Browse files
Merge pull request #9 from Stephenson-Software/feat/install-id
Send a random per-installation ID as the tag `install` (0.5.0)
2 parents 94fa0db + 2514504 commit 628bde2

4 files changed

Lines changed: 452 additions & 34 deletions

File tree

‎README.md‎

Lines changed: 63 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,9 @@ TraceClient trace = TraceClient.builder("https://trace.danielstephenson.dev", "M
1818

1919
// Say so, every startup, on the program's own logger.
2020
if (trace.isEnabled()) {
21-
getLogger().info("Usage reporting is on: MyPlugin sends its name, version and command names to "
22-
+ "https://trace.danielstephenson.dev - nothing about players or the server. "
21+
getLogger().info("Usage reporting is on: MyPlugin sends its name, version, command names and a "
22+
+ "random server ID to https://trace.danielstephenson.dev - nothing about players, and "
23+
+ "nothing that identifies the server's owner or address. "
2324
+ "Turn it off with usage-reporting.enabled: false in this plugin's config.yml, "
2425
+ "or for every plugin with enabled: false in plugins/trace/config.yml. "
2526
+ "Details: https://github.com/Stephenson-Software/trace#usage-reporting");
@@ -47,6 +48,61 @@ Before 0.4.0, `builder` took two arguments and only events tagged by hand
4748
carried a version. Upgrading is one argument: in a Bukkit plugin,
4849
`getDescription().getVersion()`.
4950

51+
## Every event carries a random server ID
52+
53+
Since 0.5.0, every event also carries the tag `install`: a random ID for
54+
the installation, so the trace server can count **distinct servers** ("active
55+
servers in the last 30 days") rather than raw events. This is the same idea
56+
as bStats' `serverUuid`, and it is said out loud here because it is the one
57+
thing the client sends that is the same from one event to the next.
58+
59+
**What it is.** A `UUID.randomUUID()`. It is not derived from anything — not
60+
a hostname, an IP address, a MAC address, a player, an account or a path. It
61+
identifies no person and no address; all it can say is "these events came
62+
from the same server". (The trace server still sees the IP address of every
63+
HTTP request, as every web server does.)
64+
65+
**Where it lives.** On a Spigot server, as the `server-id:` line of
66+
`plugins/trace/config.yml`, shared by every plugin on that server. The first
67+
time an *enabled* client finds no `server-id:` there, it appends one, under a
68+
comment that says what it is:
69+
70+
```yaml
71+
#
72+
# server-id: a random ID made on first run and sent as the tag "install", so
73+
# trace can count servers, not events. It identifies no person and no IP
74+
# address. Delete the server-id line to get a new one.
75+
server-id: 0f8b6c1e-3a52-4c8e-9a0d-6e2f1b7c4d90
76+
```
77+
78+
Nothing else in the file is touched: comments, `enabled:` and `tags:` are
79+
kept byte for byte. If the file cannot be read or written, a fresh ID is used
80+
in memory for that run only — `build()` still never throws.
81+
82+
**Resetting it.** Delete the `server-id:` line; the next start writes a new
83+
one. Or set your own value (letters, digits, `_`, `.`, `-`; at most 255
84+
characters).
85+
86+
**Opting out.** Every [opt-out](#opting-out) below also stops the ID: a
87+
disabled client never generates one, never writes one, and sends nothing.
88+
There is no way to send events without it short of turning reporting off;
89+
that is deliberate, so "how many servers" is a number that can be trusted.
90+
91+
**Programs that are not plugins.** Without `serverWideConfig(...)`, no ID is
92+
made up and no hidden file is written anywhere. A program that wants to be
93+
counted passes one it stores itself, e.g. a UUID it generated on first run
94+
and keeps in its own config:
95+
96+
```java
97+
TraceClient.builder(url, "MyCli", version).key(key)
98+
.installId(config.getString("usage-reporting.install-id")) // null or blank: none sent
99+
.build();
100+
```
101+
102+
An explicit `installId(...)` wins over `server-id:`. An event that passes its
103+
own `install` tag keeps it. `trace.installId()` returns the ID in use (`null`
104+
when disabled or when there is none), so a program can print it.
105+
50106
## What `report` promises
51107

52108
| Property | Meaning |
@@ -65,7 +121,7 @@ last word. `build()` checks these in order; the first match wins and is what
65121
| Switch | `disabledReason()` |
66122
|---|---|
67123
| Environment: `TRACE_USAGE_REPORTING=off` (or `false`, `0`, `no`) or `DO_NOT_TRACK=1` (or `true`, `yes`), case-insensitive. Always checked. | `environment` |
68-
| Server-wide, when `serverWideConfig(pluginsDirectory)` was given: `enabled: false` in `plugins/trace/config.yml`. `build()` creates the file with `enabled: true` (and a commented-out [`tags:`](#server-wide-tags) example) if it is missing and never rewrites it afterwards; it is read with a line regex, no YAML library. An IO failure is logged at `FINE` and counts as enabled. | `server-wide config: plugins/trace/config.yml` |
124+
| Server-wide, when `serverWideConfig(pluginsDirectory)` was given: `enabled: false` in `plugins/trace/config.yml`. `build()` creates the file with `enabled: true` (and a commented-out [`tags:`](#server-wide-tags) example) if it is missing; afterwards the only change it ever makes is appending a [`server-id:`](#every-event-carries-a-random-server-id) line when an enabled client finds none. It is read with a line regex, no YAML library. An IO failure is logged at `FINE` and counts as enabled. | `server-wide config: plugins/trace/config.yml` |
69125
| The program's own setting: `enabled(false)`. | `config.yml` |
70126
| No key, or a blank one. | `no key` |
71127

@@ -127,7 +183,7 @@ plugins already vendor bStats' `Metrics.java`.
127183
<dependency>
128184
<groupId>com.github.Stephenson-Software</groupId>
129185
<artifactId>trace-client-java</artifactId>
130-
<version>0.4.0</version>
186+
<version>0.5.0</version>
131187
</dependency>
132188
```
133189

@@ -138,10 +194,11 @@ Shade it into a plugin jar; it is one class.
138194
`POST {baseUrl}/api/metrics` with `Authorization: Bearer <key>` and a body of
139195

140196
```json
141-
{"application":"MyPlugin","name":"command","value":1.0,"tags":{"name":"home","version":"1.4.0"}}
197+
{"application":"MyPlugin","name":"command","value":1.0,"tags":{"name":"home","version":"1.4.0","install":"0f8b6c1e-3a52-4c8e-9a0d-6e2f1b7c4d90"}}
142198
```
143199

144-
`value` is omitted when not given; `tags` always holds at least `version`. The server assigns the
200+
`value` is omitted when not given; `tags` always holds at least `version`, and
201+
`install` whenever the client has an [installation ID](#every-event-carries-a-random-server-id). The server assigns the
145202
timestamp. A `201` is success; anything else is logged at `FINE` and dropped.
146203

147204
## Keys

‎pom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
<groupId>software.stephenson</groupId>
88
<artifactId>trace-client</artifactId>
9-
<version>0.4.0</version>
9+
<version>0.5.0</version>
1010
<packaging>jar</packaging>
1111

1212
<name>trace-client</name>

0 commit comments

Comments
 (0)