USAGE TELEMETRY

Swamp records one usage telemetry event per CLI invocation, writes it to a user-level spool directory, and sends spooled events to a telemetry endpoint. Usage telemetry is separate from OpenTelemetry trace export, which is configured by the OTEL_* variables in the OpenTelemetry reference.

Opt-outs

Each opt-out disables telemetry on its own. When any of them applies, no event is recorded and no spooled event is sent. No setting re-enables telemetry that another opt-out disables: telemetryDisabled: false in .swamp.yaml does not override the user setting, and telemetry.collection enabled does not override a repository's telemetryDisabled: true.

For SWAMP_NO_TELEMETRY and DO_NOT_TRACK, any value other than 0, false, or the empty string disables telemetry.

swamp config set telemetry.collection disabled is not itself recorded.

While an opt-out applies, events already in the spool stay on disk. They are neither sent nor deleted.

telemetry.collection

The user-level opt-out, read on every run inside or outside a repository.

$ swamp config set telemetry.collection disabled
config·set: Telemetry disabled for every run, in any repository
config·set: Restart any running swamp serve daemon to apply it

$ swamp config get telemetry.collection
config·get: "disabled"

With --json, get and set print:

{ "key": "telemetry.collection", "value": "disabled" }

Setting telemetry.collection never requires sudo.

telemetry.yaml

The file behind telemetry.collection, in the Swamp config directory.

disabled: true

A file written by hand has the same effect as swamp config set. If the file is missing, is not valid YAML, or disabled is not a boolean, telemetry is enabled.

Config directory

telemetry.yaml and the spool share the config directory, resolved in this order:

Explicit repository directory

A repository-scoped command given --repo-dir or SWAMP_REPO_DIR records nothing when that directory contains no .swamp.yaml. Commands that do not operate on a repository, such as swamp auth, swamp config, and swamp telemetry, and swamp repo init, are not affected.

Spool

Events are written to telemetry/ in the config directory, one telemetry-*.json file per event. Every run uses this spool, inside a repository or not. swamp telemetry stats reads it; see Operational Commands.

After a successful send, an event's file is deleted, or renamed to .flushed.json when the repository sets telemetryKeepFlushed.

Delivery

Each event is stamped with the endpoint in effect when it was recorded and is sent only to that endpoint. Inside a repository the endpoint is telemetryEndpoint from .swamp.yaml; otherwise it is the default endpoint.

• An event recorded in a repository with its own telemetryEndpoint stays in the spool until a run that resolves the same endpoint sends it. A run outside that repository does not send it to the default endpoint.
• An event recorded by a version of Swamp without endpoint stamping has no stamp. The next run that sends events sends it, to that run's endpoint.
• The stamp is not included in the event sent.

swamp serve

swamp serve evaluates the opt-outs once, at startup. With an opt-out in effect it records nothing and sends no spooled events. A change to telemetry.collection or telemetry.yaml takes effect when the server restarts.

A daemon installed by swamp serve daemon enable reads telemetry.yaml from the config directory of the user who enabled it.