USAGE TELEMETRY EVENTS

The Swamp CLI records one usage telemetry event per command invocation. This page describes the transport, every field of the event, what the ingest service adds, and the redaction policy. For opt-outs, the spool and delivery, see the Usage Telemetry reference. For the reasoning behind these choices, see About usage telemetry.

The envelope and redaction on this page were verified against Swamp 20260930.201417.0-sha.69135e9d.

Transport

Events

The model-method steps inside a nested workflow emit child events, and at any depth those children report the top-level run's runId and workflowName. A step still running when the run ends is recorded as an error.

Events are recorded for commands the CLI parses.

Request

Headers:

The request body identifies the install and the repository by random UUIDs. See What the ingest service adds for what the server attaches when x-api-key is present.

Flushing

When a flush fails, the CLI prints a warning and keeps the entries in the spool for the next invocation:

[WRN] swamp·cli: Telemetry flush failed (network error) — entries are queued locally and will retry on the next invocation

When swamp serve fails to deliver a batch repeatedly, it retries the entries one at a time and quarantines entries that keep failing.

Endpoint

The endpoint is resolved in this order. The first match wins. Each event is stamped with the endpoint in effect when it was recorded; see Delivery.

Local spool

Every entry is written to disk before any send is attempted, in the spool under the config directory.

Each invocation is one file named telemetry-<YYYY-MM-DD>-<id>.json, where <id> is the event's properties.id. The file holds the event's properties object. The envelope, distinct_id, and $repo_id are added when the entry is sent.

Envelope

{
  "event": "cli_invocation",
  "distinct_id": "string",
  "insert_id": "string",
  "properties": {
    "id": "string",
    "invocation": {
      "command": "string",
      "subcommand": "string",
      "commandPath": ["string"],
      "args": ["string"],
      "optionKeys": ["string"],
      "globalOptions": ["string"]
    },
    "result": {
      "status": "success | error | user_error",
      "errorType": "string",
      "errorMessage": "string",
      "exitCode": 0
    },
    "startedAt": "ISO-8601",
    "completedAt": "ISO-8601",
    "durationMs": 0,
    "swampVersion": "string",
    "denoVersion": "string",
    "platform": "string",
    "invocationContext": {
      "configuredAiTools": ["string"],
      "detectedAiTool": "string",
      "agentSessionDetected": false,
      "isInteractive": false,
      "externalDatastoreConfigured": false,
      "datastoreType": "string",
      "externalVaultConfigured": false
    },
    "parentInvocationId": "string",
    "workflowContext": {
      "workflowName": "string",
      "runId": "string",
      "jobName": "string",
      "stepName": "string",
      "modelType": "string",
      "executor": "string"
    },
    "triggerSource": "schedule | webhook | api",
    "initiatedBy": "string",
    "$repo_id": "string"
  }
}

Optional fields appear when they have a value.

Top-level fields

properties

invocation

swamp serve model-method runs record subcommand as method run and args as [<model>, <method>]. CLI commands and workflow child events record subcommand as method and args as ["run", <model>, <method>].

result

invocationContext

detectedAiTool and agentSessionDetected are derived from whether these environment variables are set, and from their values: CLAUDECODE, CLAUDE_CODE_ENTRYPOINT, TERM_PROGRAM, CURSOR_TRACE_ID, AGENT_CONTEXT_OUT, OPENCODE, CODEX_SANDBOX_NETWORK_DISABLED, CODEX_SANDBOX, PI_CODING_AGENT, AGENT, AI_AGENT, IS_AGENT. The event carries the derived tool name and boolean.

workflowContext

Identifiers

Every identifier in the envelope is a random UUID generated by Swamp.

What the ingest service adds

The ingest service stores each event's event, distinct_id, insert_id, and properties, a receive timestamp, and the account details below. When a request carries x-api-key, the service resolves the key and stores the result with each event.

Redaction

Telemetry keeps what kind of thing was done and what it was called. Names are labels, and Swamp sends them as typed. Paths, values, and queries over data are content, and Swamp redacts them before the event is built.

Argument redaction

Swamp sends a positional argument when it fills one of these named slots in the command's definition: collective, data_name, definition_name, enabled, extension, grant_id, method_name, model_id_or_name, model_or_type, name, new_name, number, old_name, output_id, output_id_or_model_name, query, report_name, run_id_or_workflow, slug, step_name, token-id, type, vault_name, vault_name_or_id, version, workflow_id_or_name, workflow_name. The argument key is sent for swamp config commands.

Every other positional argument is replaced with <REDACTED>. A value typed into a kept slot is sent as typed, whatever it contains.

swamp help sends the words that follow it while they resolve to real commands. When the positional arguments fall outside the command's definition, Swamp redacts all of them.

Error message redaction

errorMessage is the first line of the error, rewritten in this order:

1. Exact occurrences of the filesystem paths the error names, redacted argument values and their absolute forms, the working directory, $HOME, and the repository directory are replaced. A path-like value becomes <PATH>. Any other value becomes <REDACTED>.
2. file:// URLs, quoted paths, and unquoted POSIX, ~/, Windows drive, and UNC paths become <PATH>. A trailing :line:col is kept.
3. Remaining usernames in /Users/<name>, /home/<name>, and C:\Users\<name> become <REDACTED>.
4. Hostnames ending in .internal, .local, .lan, .corp, .intranet, .private, or .home become <REDACTED-HOST>.

Workflow child events and swamp serve events apply steps 2 to 4.

An event contains exactly the fields described in Envelope.

Worked example

This command, run inside a repository, points --server at an unreachable internal host:

swamp model create command/shell other --server http://build01.corp:9090

Error: Could not connect to ws://build01.corp:9090/: NetworkError: failed to connect to WebSocket: dns error

It produces this event. UUIDs and timestamps vary.

{
  "event": "cli_invocation",
  "distinct_id": "cbd26c76-...",
  "insert_id": "1cc948c9-...",
  "properties": {
    "id": "1cc948c9-...",
    "invocation": {
      "command": "model",
      "args": ["command/shell", "other"],
      "optionKeys": ["--server"],
      "globalOptions": [],
      "subcommand": "create",
      "commandPath": ["model", "create"]
    },
    "result": {
      "status": "user_error",
      "exitCode": 1,
      "errorType": "UserError",
      "errorMessage": "Could not connect to ws://<REDACTED-HOST>:9090/: NetworkError: failed to connect to WebSocket: dns error"
    },
    "startedAt": "2026-09-30T22:26:26.132Z",
    "completedAt": "2026-09-30T22:26:26.172Z",
    "durationMs": 40,
    "swampVersion": "20260930.201417.0-sha.69135e9d",
    "denoVersion": "2.9.7",
    "platform": "linux",
    "invocationContext": {
      "agentSessionDetected": true,
      "isInteractive": false,
      "externalDatastoreConfigured": false,
      "externalVaultConfigured": false,
      "configuredAiTools": ["claude"],
      "detectedAiTool": "claude"
    },
    "$repo_id": "caec33e6-..."
  }
}

Swamp kept the model type and name, recorded the flag name --server, and wrote the host in the error as <REDACTED-HOST>.

Other commands, as recorded in args:

Verifying

To read exactly what is sent, point the endpoint at a local listener that answers 202, run any command, and read the request body:

SWAMP_TELEMETRY_ENDPOINT=http://127.0.0.1:8080 swamp model get my-model

To read each entry on disk before it is sent, point the endpoint at a closed loopback port. The entry stays in <config>/telemetry/:

SWAMP_TELEMETRY_ENDPOINT=http://127.0.0.1:1 swamp model get my-model

Opt-outs

swamp config set telemetry.collection disabled, telemetryDisabled: true in .swamp.yaml, SWAMP_NO_TELEMETRY, DO_NOT_TRACK, and --no-telemetry each turn usage telemetry off. See Opt-outs for the scope of each, and Turn Off Usage Telemetry for the steps.

Other outbound requests

SWAMP_NO_UPDATE_CHECK accepts the same values as SWAMP_NO_TELEMETRY. Extension auto-resolve runs inside a repository. See Trust Configuration.