ABOUT USAGE TELEMETRY

The Swamp CLI sends one small event per command. The event records which command ran, how long it took, and how it finished. It is designed so that a security reviewer can read the Usage Telemetry Events reference and hold the product to it. This page explains the decisions behind that design.

Names and content

Telemetry draws its line between what a thing is called and what is inside it. A model named prod-db and a method named backup are labels someone chose so that other people could refer to them. They tell Swamp Club which parts of the product are used, and they are already shared with anyone who reads the repository. The path the backup writes to, the --input values passed to it, and the output it produces are the work itself, and Swamp redacts them.

Search queries are kept for the same reason names are: they say what someone was looking for in the registry. A swamp data query predicate is a query over the user's own data, so Swamp redacts it.

Redaction as an allowlist

Each command declares its arguments by name. Swamp sends the arguments that fill a fixed list of name-holding slots, such as model_id_or_name or workflow_name, and replaces every other argument with <REDACTED>. A new command's arguments start out redacted, and a slot joins the list once someone decides it holds a name.

A slot on the list is trusted for whatever is typed into it. A path typed where a model name belongs is sent as typed, because the slot says it is a name. The reference states this plainly.

Error messages are free text, so Swamp scrubs them. It first replaces the values it already knows are sensitive, such as the paths an error names, the redacted arguments, the working directory, and the home directory, by exact match. Pattern rules then rewrite paths, home-directory usernames, and internal hostnames. Swamp keeps the first line, which names the error.

The spool comes first

Swamp writes every event to disk before it sends anything. The exact bytes that will leave the machine sit in a plain file the user can read, and every event survives a network failure to be sent on the next run. Pointing the endpoint at a closed port turns the spool into an audit log: every event waits in <config>/telemetry/ to be read.

Every opt-out stands on its own

A repository is shared, and a machine is personal. telemetryDisabled in .swamp.yaml lets a team opt a repository out for everyone who clones it. swamp config set telemetry.collection disabled opts a user out in every repository and outside them. SWAMP_NO_TELEMETRY and DO_NOT_TRACK cover an environment such as a CI job, and --no-telemetry covers one command.

Each opt-out turns telemetry off by itself, and a decision to opt out holds wherever it was made: the person who opted out, the team that committed the setting, and the pipeline that set the variable each get the result they chose. See Opt-outs.

Attribution

The event body identifies an install and a repository by random UUIDs. When the CLI is signed in, it sends its API key in a header, and the ingest service resolves that key to an account and stores the username with the event. This is how activity is attributed to an operative's profile. Once a signed-in event has linked an install's distinct_id to an account, later events from that install are attributed to the same account.