@@ -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.
2020if (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
4748carried 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
145202timestamp. A `201` is success; anything else is logged at `FINE` and dropped.
146203
147204# # Keys
0 commit comments