Ster/Docs

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#

text
ster telemetry status
ster telemetry on --level errors|usage
ster telemetry off
ster telemetry show
ster telemetry export <FILE>
ster telemetry flush
ster telemetry events

Ster 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.

EventConsentWhat it saysProperties
failureerrorsa command or screen failed: where, the declared cause, the sentence and the fix it showed, without your home directory or this machine's namefailure_point, error_code, severity, retryable, outage, service, impact, detail, remedy, cause_id, context, causes
cli.commandusagea command finished: its name only, never its arguments, how it exited and how long it tookcommand, exit_status, duration_ms
frustration.repeat_failureerrorsthe same failure happened again: how many times in a row and the seconds since the previous onefailure_point, consecutive, seconds_since_previous
frustration.usage_loopusagethe same command was refused as a usage error again: its name, how many times in a row and the seconds since the previous onecommand, consecutive, seconds_since_previous
frustration.help_after_failureusagehelp was asked for after a failure: the command it was asked about, which failure came before it and how long beforecommand, 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#

InputRequiredMeaning
--level errors|usagewith onWhat to send from now on.
<FILE>with exportWhere to write every waiting event as one JSON array, for a machine without network.
WISENT_TELEMETRY_HOMEnoThe directory telemetry keeps its state in; otherwise $XDG_STATE_HOME/ster/telemetry, else ~/.local/state/ster/telemetry.
WISENT_TELEMETRY_COLLECTOR_URLnoThe 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=1noSend 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#

  • --level other than errors or usage is 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:// (or http:// on the loopback) is refused as reading the collector address from <source>: a collector address must be https://, or http:// on a loopback host; observed: <source> holds <address>.
  • flush prints 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, or the 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.