ster telemetry
Read and change what this installation reports to Ster's maintainers when something fails, see exactly what waits to be sent, and send it.
Invocation and purpose#
ster telemetry status
ster telemetry on --level errors|usage
ster telemetry off
ster telemetry show
ster telemetry export <FILE>
ster telemetry flush
ster telemetry eventsSter sends nothing until you answer. The first command you run on a terminal asks once whether Ster may send its failures (errors), its failures and the commands that ran (usage), or nothing; a script, a pipe or a coding agent is never asked, and stays at nothing until someone runs ster telemetry on. DO_NOT_TRACK=1 sends nothing whatever was answered.
With errors, a command that fails queues its failure: where it failed, the declared cause from `ster errors list`, the sentence and the fix it printed. With usage, every command also queues its name (pairs import), its exit status and how long it took. No file, prompt, pair, model output or command argument is ever sent, and your home directory and this machine's host name are replaced by ~ and <this-host> before anything is queued. When a command ends with events waiting, Ster starts ster telemetry flush in the background and exits at once, so you never wait for it.
Ster also counts three signals that something is not working for you, because only it sees the order of what happened. With errors, the same failure again queues frustration.repeat_failure with its failure point, how many times in a row and the seconds since the previous one. With usage, the same command refused as a usage error (exit 2) again queues frustration.usage_loop with the command's name, and --help or ster help right after a failure queues frustration.help_after_failure with the command asked about and which failure came before; neither carries an argument. They carry no thresholds: how many repeats make a problem is decided by Ster's maintainers from what is sent.
What is sent#
Every kind of event Ster can send, as ster telemetry events prints it. Nothing else can be sent: Ster's reporter queues only an event listed here, with exactly these properties, and node src/cli/check-telemetry-events.mjs refuses this page when it and ster telemetry events disagree.
| Event | Consent | What it says | Properties |
|---|---|---|---|
failure | errors | a command or screen failed: where, the declared cause, the sentence and the fix it showed, without your home directory or this machine's name | failure_point, error_code, severity, retryable, outage, service, impact, detail, remedy, cause_id, context, causes |
cli.command | usage | a command finished: its name only, never its arguments, how it exited and how long it took | command, exit_status, duration_ms |
frustration.repeat_failure | errors | the same failure happened again: how many times in a row and the seconds since the previous one | failure_point, consecutive, seconds_since_previous |
frustration.usage_loop | usage | the same command was refused as a usage error again: its name, how many times in a row and the seconds since the previous one | command, consecutive, seconds_since_previous |
frustration.help_after_failure | usage | help was asked for after a failure: the command it was asked about, which failure came before it and how long before | command, failure_point, seconds_since_failure |
Every event also carries the envelope the collector takes: an event id, ster-cli, the platform, the event name, this installation's random id, a session id, Ster's version, the system's version and the time.
ster telemetry events prints the same list as JSON: [{ "name", "consent", "summary", "properties" }].
Inputs and options#
| Input | Required | Meaning |
|---|---|---|
--level errors|usage | with on | What to send from now on. |
<FILE> | with export | Where to write every waiting event as one JSON array, for a machine without network. |
WISENT_TELEMETRY_HOME | no | The directory telemetry keeps its state in; otherwise $XDG_STATE_HOME/ster/telemetry, else ~/.local/state/ster/telemetry. |
WISENT_TELEMETRY_COLLECTOR_URL | no | The collector to send to instead of Wisent's public one, https://telemetry.wisent.com/api/analytics/mobile/collect: https://, or http:// on this machine's loopback. |
DO_NOT_TRACK=1 | no | Send nothing. |
Output and state#
status, on and off print the installation's state: level (unanswered, off, errors or usage), do_not_track, the collector and what named it (collector_source: wisent-errors for the public collector, or WISENT_TELEMETRY_COLLECTOR_URL), the random installation id made with the first queued event, how many events are queued, the last_delivery (when, how many were sent, how many remaining, and why it stopped), and the directory. off also drops every waiting event. show prints the waiting events exactly as they will be sent; export writes them and prints { "file", "events" }. flush sends them oldest first, removes each the collector accepted, and prints { "sent", "remaining", "stopped", "skipped" }; skipped says why nothing was attempted (unanswered, off, DO_NOT_TRACK).
The state lives in consent.json, installation.json, queue/<event>.json and delivery.json under the directory above. ster request, which Ster Desktop runs, reports nothing itself.
Refusals#
--levelother thanerrorsorusageis a usage error with status 2.- A directory that cannot be written is refused as
keeping <what> in <path>: the telemetry directory could not be written: <error>; observed: directory <directory>; fix: make <directory> writable by this user, or name a writable one with WISENT_TELEMETRY_HOME. - A state file telemetry did not write is refused as
reading <what> from <path>: the file is not what telemetry wrote: <error>; observed: the file holds <n> bytes; fix: answer again with \ster telemetry on|off\, which rewrites it, or remove <path>, and nothing is sent while it stands. - A collector address that is not
https://(orhttp://on the loopback) is refused asreading the collector address from <source>: a collector address must be https://, or http:// on a loopback host; observed: <source> holds <address>. flushprints what it sent and exits 1 with the reason it stopped, the events staying queued:the collector refused HTTP <status>: <its answer>when the collector declines the event,the collector could not be reached: <error>without network, orthe answer is not the collector's {"ok": true}when the address is not Echo's app collector.- Every telemetry failure that happens while another command runs is said once on stderr, starting with
wisent-errors: telemetry:, and never changes that command's output or exit status.