Skip to main content

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

The key travels with the event, so it goes to whichever endpoint the CLI resolved, not only to telemetry.swamp-club.com. That is deliberate. An organization that runs its own collector, on-premises or alongside its own Swamp Club server, needs the key to attribute events in the same way, and binding the key to one origin would break attributed telemetry for those deployments. The CLI therefore does not check that an endpoint belongs to the server that issued the key. The endpoint order decides where the key goes.

That makes a custom endpoint trusted deployment configuration, the same kind of decision as which server to sign in to. For whoever runs a deployment, it means:

  • Point telemetryEndpoint or SWAMP_TELEMETRY_ENDPOINT only at a collector you run, and serve it over https://. An http:// endpoint receives the key unencrypted.
  • For an organization-managed fleet, set SWAMP_TELEMETRY_ENDPOINT on the machines: it applies in every repository and outranks any repository's telemetryEndpoint.
  • .swamp.yaml is content that travels with a repository, and it is not a security boundary. A repository from someone you do not trust can name a collector its author runs, and a signed-in CLI would send that collector its key. Before running commands in such a repository, set SWAMP_TELEMETRY_ENDPOINT, or opt out with --no-telemetry or SWAMP_NO_TELEMETRY.