Relationships
#4683 serve: telemetry for integrations: report hosted integrations to swamp-club, a client kind on usage events, and events for approvals and run control
Opened by skunk-ape · 11/12/2026· Shipped 11/12/2026
Part of #4459. Sibling swamp-club issue: #4684 (stores the integrations serve reports, and sends serve-link events to analytics). Integration links are open to every collective with trial, paid or admin standing (#4622), so we need to see how integrations are used.
Problem
From swamp's origin/main (285ddf5ce), here is what reaches us centrally for each integration event:
- An integration is added to, or revoked from, a serve. Nothing.
swamp access integration registersends only the generic usage event, with the integration id redacted (src/cli/telemetry_invocation.ts:91). Serve's instance registration (src/serve/oauth_client.ts:214-222) and its hourly heartbeat (body{instanceId},src/serve/oauth_client.ts:288) name no integrations. swamp-club first learns an integration exists when someone starts a link. - An action through an integration (a delegated token). Serve sends usage events for workflow runs and method runs (
src/serve/deps.ts:582,src/serve/handlers/workflow_handlers.ts:637,800,src/serve/handlers/model_handlers.ts:814,1212), withtriggerSourceandinitiatedBy. However:- The request's
client(integration:<id>) and its delegation never reach the telemetry entry, so a run from Slack looks the same as a CLI--serverrun or a dashboard run. - Approve, reject, resume, signal and cancel send no usage event at all (
handleWorkflowApprove/Reject/Resume,workflow_handlers.ts:1944,2389,2913). For integrations, approvals are the main thing people do. - The collective is there only when serve runs with a collective key.
- The request's
- A leak. The CLI deliberately redacts integration ids. But
access integration ceilingandrevokewith--serverrun the behavior namedintegration-<id>(src/cli/commands/access_integration.ts:275-277), and serve sends behavior names as-is (src/serve/telemetry.ts:49-61). So the id reaches telemetry anyway.access group add-member/remove-memberwith--serverdo the same with the group name (src/cli/commands/access_group.ts:377-381,456-460), which the CLI also redacts locally.
The full record (client, delegation, person, outcome) exists only in the customer's local audit log and run records.
Proposed change
- Report integrations to swamp-club. On instance registration, and when the set changes (register, revoke), serve sends the integrations it hosts: id, state, createdAt and revokedAt. This channel is functional and doesn't follow telemetry opt-outs, so it carries ids, states and dates only: no names, ceilings or member details. swamp-club stores them (sibling issue). A swamp-club that doesn't know the field must still accept registration and heartbeat, so the two can ship in either order.
clientkind and integration id on serve's usage events. Pass the request's client intocreateRunTelemetry/createCommandTelemetryand add aclientproperty to the telemetry entry. It holds the kind:integration,direct:cli,direct:dashboardordirect:token. Events from an integration also carryintegrationId, the same id item 1 reports and link start sends, so usage joins per integration. Events with no client omit both. No event carries a delegation id. The CLI stops redactingaccess integration <verb> <id>(telemetry_invocation.ts:92), so the CLI and serve treat the id the same way.- Events for gate and run control. Approve, reject, resume, signal and cancel send the same usage event as runs, with
triggerSource,initiatedByandclient. Refusals (resume_inputs_refusedand access denials) are counted with their outcome, without detail. Each action sends exactly one event, whichever route it came in on; a resume that an approval or signal starts by itself is not counted as a resume. Bulk cancel (POST /api/v1/cancel) sends one event per request with the number of runs cancelled, not one per run. - Collective on serve events. Add
serveCollectives, the slugs of the collectives serve allows, whatever key it runs with. It's a list because serve can allow several; serve knows slugs, not ids. It is a separate name from thecollective_id/collective_slugthat ingest attests and overwrites for a collective key. - Close the leak. Serve's method-run events for
swamp/integrationand access groups send the type and method, not the instance name. For integrations the id then arrives one way only, asintegrationId; group names are operator-chosen and stay out of telemetry. Other id-derived behavior names (grants, delegations, workers, leases) are generated or never reach the method-run handler. - Document the new properties in the usage telemetry reference. It's in swamp-club, so it's part of the sibling issue.
Opt-outs (--no-telemetry, SWAMP_NO_TELEMETRY, DO_NOT_TRACK, telemetryDisabled, the user setting) keep turning off 2–5, so action counts stay lower bounds. Item 1 is the complete count of integrations.
Done when
- Registering and revoking an integration on a serve reaches swamp-club's registration or heartbeat call with id, state and dates, and no name. Tested against a swamp-club that knows the field and one that doesn't.
- A workflow run, method run, approve, reject, resume, signal and cancel made with a delegated token each send a usage event with
client: "integration"and that integration'sintegrationId. The same actions from the CLI and dashboard carry their own kind and nointegrationId. No event carries a delegation id. - Serve events carry
serveCollectiveswhen serve allows at least one collective. - A bulk cancel sends one event carrying the count.
access integration ceiling/revoke --serversend nointegration-<id>name, andaccess group add-member/remove-member --serversend no group name. A test asserts no delegation id appears in any serve telemetry payload, and an integration id appears only asintegrationId.- The CLI's
access integration <verb> <id>sends the id. - With telemetry switched off, none of 2–5 is sent.
- swamp-uat's strict schemas are updated where output changes.
Out of scope
Dashboards and queries over the data. Sending integration names. Changing the local audit log, which already records client.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.