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
| Source | Events |
|---|---|
| Any CLI command | One cli_invocation event. |
swamp workflow run |
One event for the command, plus one child event per behavior method step. Children carry parentInvocationId. |
swamp serve |
One event per workflow run, behavior method run, approve, reject, resume, signal and cancel it executes, plus one event for the server process when it exits. |
The behavior 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
| Property | Value |
|---|---|
| Method | POST |
| URL | <endpoint>/ingest |
| Content type | application/json |
| Single event | The event object, bare |
| Batch | { "events": [ ... ] } |
| Batch limits | 500 events and 1 MiB per request |
| Delivered | HTTP 202. Other statuses keep the entry in the spool for retry. |
| Refused | An event name the endpoint does not accept is dropped, still 202. |
Headers:
| Header | Sent | Value |
|---|---|---|
User-Agent |
Always | swamp-cli/<swampVersion> |
x-api-key |
When the CLI holds an API key | The active API key |
The active API key is the first of: the file named by --club-api-key-file on a
command that takes it, such as swamp serve, the file named by
SWAMP_API_KEY_FILE, SWAMP_API_KEY, and the key stored by swamp auth login.
It can be a personal or a collective API key. It is sent to the resolved
endpoint.
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
| Process | When | Entries | Time limit |
|---|---|---|---|
| CLI command | At the end of every command | Up to 25 unsent entries, oldest day first | 2 seconds |
swamp serve |
Every 60 seconds | Up to 20 batches of unsent entries | 10 seconds |
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 invocationWhen 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.
| Priority | Source |
|---|---|
| 1 | SWAMP_TELEMETRY_ENDPOINT environment variable |
| 2 | telemetryEndpoint in .swamp.yaml |
| 3 | http://localhost:8080 when the auth server is localhost, 127.0.0.1, or [::1] |
| 4 | https://telemetry.swamp-club.com |
The resolved endpoint also receives the x-api-key header whenever the CLI
holds an API key. The CLI does not check that the endpoint belongs to the server
that issued the key, and sends the header over the endpoint's own scheme: an
http:// endpoint receives the key unencrypted. A custom endpoint is trusted
deployment configuration and must be a collector controlled by whoever runs the
deployment. See
About usage telemetry.
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.
| File | Removed |
|---|---|
| Sent entry | Immediately |
Sent entry, with telemetryKeepFlushed: true |
Renamed to .flushed.json, deleted after 2 days |
| Unsent entry | After 7 days, by a CLI command that succeeds |
Quarantined entry (.quarantined.json) |
After 30 days. Written by swamp serve. |
Last flush record
Each flush that sends, or tries to send, entries writes flush-state.json in
the same telemetry/ directory, for CLI and swamp serve flushes alike. A
flush with nothing to send writes nothing. The write is best-effort: a failure
to write the record never changes the flush outcome, and a record that does not
parse reads as absent.
| Field | Type | Description |
|---|---|---|
lastAttemptAt |
string | ISO 8601 time of the last flush attempt |
lastAttemptOk |
boolean | Whether the last attempt succeeded |
lastFailureReason |
string | Why the last attempt failed, up to 200 characters. Optional |
lastSuccessAt |
string | ISO 8601 time of the last successful send. Optional |
lastSentCount |
integer | Number of entries the last successful send delivered. Optional |
Empty spool
When
swamp telemetry stats
finds no entries in its window, it prints No telemetry data found. followed by
one explanation:
| State | Explanation |
|---|---|
| Opted out | Telemetry is turned off by <sources>, so nothing is recorded. and how to turn it back on: swamp config set telemetry.collection enabled, unset SWAMP_NO_TELEMETRY or unset DO_NOT_TRACK |
| No flush recorded | No user-level or environment opt-out is set, and no flush has been recorded on this machine yet. |
| Last flush succeeded | Sent entries are removed from the spool, with the time and entry count of the last successful send, then Set telemetryKeepFlushed: true in a repository's .swamp.yaml to keep sent entries for inspection. |
| Last flush failed | The time and reason of the failed attempt, and that unsent entries stay queued. When --days is under 7, Run swamp telemetry stats --days 7 to include them. The last successful send follows, if there was one |
The opt-out sources named are telemetry.collection, SWAMP_NO_TELEMETRY and
DO_NOT_TRACK. The command does not read a repository, so a repository's
telemetryDisabled or --no-telemetry is not named.
With --json, the output keeps message and adds the state:
{
"message": "No telemetry data found",
"telemetryEnabled": true,
"disabledBy": [],
"lastFlush": {
"lastAttemptAt": "2026-11-05T09:12:44.103Z",
"lastAttemptOk": true,
"lastSuccessAt": "2026-11-05T09:12:44.103Z",
"lastSentCount": 3
},
"daysAnalyzed": 2,
"keepFlushedKey": "telemetryKeepFlushed"
}| Field | Description |
|---|---|
message |
Always No telemetry data found |
telemetryEnabled |
false when an opt-out is in effect |
disabledBy |
The opt-out sources in effect |
lastFlush |
The last flush record, or null when none exists |
daysAnalyzed |
The --days window |
keepFlushedKey |
The .swamp.yaml key that keeps sent entries: telemetryKeepFlushed |
With telemetryKeepFlushed: true, the kept .flushed.json entries are counted
by swamp telemetry stats, so the spool is not empty while they last.
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"],
"commandSpelling": "model | behavior | behaviour"
},
"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,
"authMode": "verified | offline | none"
},
"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
| Field | Type | Required | Value |
|---|---|---|---|
event |
string | Yes | Always cli_invocation. |
distinct_id |
string | Yes | Random per-install UUID from <config>/identity.json. Falls back to $repo_id when identity.json is unavailable. |
insert_id |
string | Yes | Random per-event UUID, equal to properties.id. The ingest service drops a repeated insert_id. |
properties |
object | Yes | The fields below. |
properties
| Field | Type | Required | Value |
|---|---|---|---|
id |
string | Yes | Random per-event UUID. |
invocation |
object | Yes | See invocation. |
result |
object | Yes | See result. |
startedAt |
string | Yes | ISO-8601 timestamp. |
completedAt |
string | Yes | ISO-8601 timestamp. |
durationMs |
number | Yes | Milliseconds between startedAt and completedAt. |
swampVersion |
string | Yes | The CLI version, e.g. 20260930.201417.0-sha.69135e9d. |
denoVersion |
string | Yes | The embedded Deno runtime version, e.g. 2.9.7. |
platform |
string | Yes | Operating system: linux, darwin, or windows. |
invocationContext |
object | No | See invocationContext. |
parentInvocationId |
string | No | Present on workflow child events. The id of the swamp workflow run event. |
workflowContext |
object | No | Present on workflow child events and swamp serve workflow runs. See workflowContext. |
triggerSource |
string | No | Present on swamp serve runs. schedule, webhook, or api. |
initiatedBy |
string | No | Present on swamp serve runs. The principal that started the run: user:<id>, service:<name>, worker:<name>, or ghost. |
client |
string | No | Present on swamp serve events from a request that names its client: integration, direct:cli, direct:dashboard, or direct:token. |
integrationId |
string | No | Present when client is integration. The id of the integration that made the request. |
serveCollectives |
string[] | No | Present on swamp serve events when the serve has allowed collectives configured: their slugs. Sent whatever key the serve uses. |
cancelledCount |
number | No | Present on a swamp serve bulk cancel: how many executions it cancelled. |
$repo_id |
string | No | Random per-repository UUID from repoId in .swamp.yaml. Present when the command resolved a repository. |
invocation
| Field | Type | Required | Value |
|---|---|---|---|
command |
string | Yes | First word of the command, e.g. model. |
subcommand |
string | No | Second word of the command, e.g. method. |
commandPath |
string[] | No | The resolved command from the CLI's own command tree, e.g. ["model","method","run"]. |
args |
string[] | Yes | Positional arguments after the command words, redacted as described in Redaction. |
optionKeys |
string[] | Yes | Flag names as typed, e.g. --input. An undeclared flag is recorded as <UNKNOWN_OPTION>. |
globalOptions |
string[] | Yes | Global flags used: --json, -q, --quiet, -v, --verbose, --no-telemetry, --no-color, --show-properties. |
commandSpelling |
string | No | The root word typed for a behavior command: model, behavior, or behaviour. Absent for every other command group. |
A behavior command is recorded with the model compatibility identifiers
whichever word was typed: command is model and commandPath is the model
command path. swamp behavior run my-behavior execute records subcommand as
method, commandPath as ["model","method","run"] and args as
["run","my-behavior","execute"]. commandSpelling keeps the word that was
typed.
swamp serve behavior method runs record subcommand as method run and
args as [<behavior>, <method>]. CLI commands and workflow child events
record subcommand as method and args as ["run", <behavior>, <method>].
Method runs of @swamp/integration and access-group behaviors record the type,
for example @swamp/integration, in place of the behavior name.
swamp serve records the other actions it executes like this, each with
triggerSource api and empty args:
| Action | command |
subcommand |
|---|---|---|
| Approve, reject, resume, signal or cancel a run | workflow |
approve, reject, resume, signal, or cancel |
| Cancel one behavior method run | model |
method cancel |
Cancel every execution (POST /api/v1/cancel) |
cancel |
all |
A request the caller got wrong (an access denial, an invalid state, a run that
does not exist, refused resume inputs) is recorded with status user_error. A
failure inside the serve while handling the action is recorded with status
error. Either way errorType holds the serve's error code, for example
resume_inputs_refused or workflow_cancel_failed, and errorMessage is left
out. A resume that an approval or signal starts sends no event of its own.
client, integrationId, serveCollectives, cancelledCount, the actions
above, and the kept id slot under swamp access integration come with the
Swamp release after the version this page was verified against.
result
| Field | Type | Required | Value |
|---|---|---|---|
status |
string | Yes | success, user_error (the error is a user error), or error. |
exitCode |
number | Yes | 0 on success, 1 on error. |
errorType |
string | No | The error's class name, e.g. UserError. On swamp serve approve, reject, resume, signal and cancel events, the serve's error code. |
errorMessage |
string | No | The first line of the error message, after redaction. |
invocationContext
| Field | Type | Required | Source |
|---|---|---|---|
configuredAiTools |
string[] | No | tools in .swamp.yaml. Present when the command resolved a repository. |
detectedAiTool |
string | No | claude, cursor, kiro, opencode, codex, or pi, derived from the variables below. |
agentSessionDetected |
boolean | Yes | Derived from the variables below. |
isInteractive |
boolean | Yes | Whether stdin is a terminal. |
externalDatastoreConfigured |
boolean | Yes | Whether datastore.type in .swamp.yaml is set to anything other than filesystem. |
datastoreType |
string | No | datastore.type in .swamp.yaml. |
externalVaultConfigured |
boolean | Yes | Whether any vault in the repository uses a provider other than local_encryption or mock. |
authMode |
string | No | How the account check let the command run: verified, offline (swamp-club could not be reached and a stored proof or the 24-hour grace window carried the run), or none (the command is exempt or was blocked). |
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
| Field | Type | Required | Value |
|---|---|---|---|
workflowName |
string | Yes | Name of the top-level workflow. |
runId |
string | Yes | Random per-run UUID of the top-level run. |
jobName |
string | Yes | Name of the job containing the step. |
stepName |
string | Yes | Name of the step. |
modelType |
string | No | Type of the behavior the step ran, e.g. command/shell. |
executor |
string | No | Where the step ran: loopback or a worker name. |
Identifiers
Every identifier in the envelope is a random UUID generated by Swamp.
| Identifier | Scope | Stored in |
|---|---|---|
distinct_id |
Per install | <config>/identity.json |
insert_id, properties.id |
Per event | The event |
$repo_id |
Per repository | repoId in .swamp.yaml |
runId |
Per workflow run | The workflow run record |
parentInvocationId |
Per invocation | The event |
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.
| Key type | Stored with each event |
|---|---|
| Personal API key | The account's username. |
| Collective API key | distinct_id replaced by collective:<collective id>. The collective's id and slug, and its members' user ids and usernames, added to properties. |
| No key | The username previously linked to the event's distinct_id, if a signed-in event from the same install has linked one. |
Events Swamp Club records
Swamp Club writes some events to the same store itself, from actions on the site
and from the swamp serve link API. They do not pass through the ingest
service.
Integration link events
Each step of an
integration link records
one event named serve_link_<kind>.
| Event | Recorded when |
|---|---|
serve_link_requested |
A serve starts a link. |
serve_link_approved |
A person approves the link on the consent page. |
serve_link_denied |
A person denies the link on the consent page. |
serve_link_approval_refused |
Swamp Club refuses an approval, for example because the account does not match. |
serve_link_report_refused |
The serve reports that it refused an approved link. |
serve_link_recorded |
The serve reports the link recorded, and Swamp Club stores it. |
serve_link_emailed |
Swamp Club sends the person the notice of the new link. |
serve_link_email_failed |
Sending that notice failed. |
serve_link_ended |
The link ends, whether the person, the serve, the collective or Swamp Club ended it. |
| Field | Value |
|---|---|
distinct_id |
The person's account id for approved, denied and approval_refused, the decisions they make signed in. collective:<collective id> for every other event. |
properties.client_id |
The serve's OAuth client id. |
properties.collective_id |
The collective the serve belongs to. |
properties.integration_id |
The integration id the serve sent when it started the link. |
properties.platform |
The integration's platform, for example slack. |
properties.request_id |
The link request's id. Present on events about a request. |
properties.link_id |
The link's id. Present once the link is recorded. |
properties.reason |
Present on ended and approval_refused: a code from a fixed set, such as plan_lapsed or disowned. |
These events carry no username, no email address and nothing from the platform identity the serve sent (team, user id, display name or workspace). Reasons a serve or a mail provider writes in free text stay out of them.
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.
| Kept as sent | Redacted before the event is built |
|---|---|
Command words at any depth (commandPath) |
Positional arguments outside the kept slots: <REDACTED> |
| Behavior, workflow, job, step, and vault names | Flag values, including --input values |
| Behavior types and method names, including private extensions | swamp vault put keys and values |
| Search queries | swamp data query predicates |
| Flag names | Everything after -- |
| Error class, and the first line of the error after redaction | Paths, home-directory usernames, and internal hostnames in error messages |
Argument redaction
Swamp sends a positional argument when it fills one of these named slots in the
command's definition: behavior_id_or_name, behavior_or_type, 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_behavior_name,
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, and id under
swamp access integration only. The argument key is sent for swamp config
commands. id stays redacted under swamp access delegation.
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:
- 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>. file://URLs, quoted paths, and unquoted POSIX,~/, Windows drive, and UNC paths become<PATH>. A trailing:line:colis kept.- Remaining usernames in
/Users/<name>,/home/<name>, andC:\Users\<name>become<REDACTED>. - Hostnames ending in
.internal,.local,.lan,.corp,.intranet,.private, or.homebecome<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 behavior create command/shell other --server http://build01.corp:9090Error: Could not connect to ws://build01.corp:9090/: NetworkError: failed to connect to WebSocket: dns errorIt 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"],
"commandSpelling": "behavior"
},
"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-10-14T04:01:56.271Z",
"completedAt": "2026-10-14T04:01:56.329Z",
"durationMs": 58,
"swampVersion": "20261014.023540.0-sha.7b10a478",
"denoVersion": "2.9.7",
"platform": "darwin",
"invocationContext": {
"agentSessionDetected": true,
"isInteractive": false,
"externalDatastoreConfigured": false,
"externalVaultConfigured": false,
"configuredAiTools": ["claude"],
"detectedAiTool": "claude",
"authMode": "verified"
},
"$repo_id": "caec33e6-..."
}
}Swamp kept the behavior type and name, recorded the command in its model form
with commandSpelling set to behavior, recorded the flag name --server, and
wrote the host in the error as <REDACTED-HOST>.
Other commands, as recorded in args:
| Command | args |
|---|---|
swamp vault put prod-secrets DB_PASSWORD hunter2 |
["prod-secrets","<REDACTED>","<REDACTED>"] |
swamp data query 'attributes.owner == "alice@example.com"' |
["<REDACTED>"] |
swamp extension search aws |
["aws"] |
swamp behavior run my-behavior execute -- --secret=/etc/shadow |
["run","my-behavior","execute","<REDACTED>"] |
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 behavior get my-behaviorTo 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 behavior get my-behaviorOpt-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
| Request | When | Turn off |
|---|---|---|
| Update check | At most once per 24 hours, after a command succeeds, for non-JSON output, when automatic updates are off. A HEAD request to https://artifacts.swamp-club.com with a 5-second timeout. |
SWAMP_NO_UPDATE_CHECK=1 |
| Extension auto-resolve | When a command needs an extension type from a trusted collective that is missing locally. | trustedCollectives: [] in .swamp.yaml, with trustMemberCollectives left false |
whoami |
When SWAMP_API_KEY is set and the cached username or token scopes are missing. |
Unset SWAMP_API_KEY |
| Serve registration | When swamp serve registers with Swamp Club, at each heartbeat, and when an integration is added to or revoked from the serve. Sends the integrations the serve hosts: each one's id, state, and the dates it was created and revoked. No names, ceilings or member details. |
Not turned off by telemetry opt-outs. It is how Swamp Club runs the serve's links. |
| Inbox check | After the account check passes, during workflow run, behavior run, extension pull and extension push, at most once every 15 minutes per API key and server, longer if Swamp Club asks, and never in a nested run. A GET /api/inbox/summary to the Swamp Club server you are signed in to, sending your API key, with a 5-second timeout. It adds at most 250 ms to the end of the command. |
SWAMP_NO_INBOX_NOTICE=1, or CI set to anything but an empty string, 0 or false |
SWAMP_NO_UPDATE_CHECK and SWAMP_NO_INBOX_NOTICE accept the same values as
SWAMP_NO_TELEMETRY.
The inbox check is not telemetry: SWAMP_NO_TELEMETRY, DO_NOT_TRACK,
--no-telemetry and telemetry.collection disabled do not turn it off. It
fills the cache behind the
inbox notice. Extension
auto-resolve runs inside a repository. See
Trust Configuration.