Skip to main content
← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneesskunk-ape

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 register sends 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), with triggerSource and initiatedBy. 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 --server run 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.
  • A leak. The CLI deliberately redacts integration ids. But access integration ceiling and revoke with --server run the behavior named integration-<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-member with --server do 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

  1. 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.
  2. client kind and integration id on serve's usage events. Pass the request's client into createRunTelemetry / createCommandTelemetry and add a client property to the telemetry entry. It holds the kind: integration, direct:cli, direct:dashboard or direct:token. Events from an integration also carry integrationId, 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 redacting access integration <verb> <id> (telemetry_invocation.ts:92), so the CLI and serve treat the id the same way.
  3. Events for gate and run control. Approve, reject, resume, signal and cancel send the same usage event as runs, with triggerSource, initiatedBy and client. Refusals (resume_inputs_refused and 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.
  4. 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 the collective_id / collective_slug that ingest attests and overwrites for a collective key.
  5. Close the leak. Serve's method-run events for swamp/integration and access groups send the type and method, not the instance name. For integrations the id then arrives one way only, as integrationId; 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.
  6. 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's integrationId. The same actions from the CLI and dashboard carry their own kind and no integrationId. No event carries a delegation id.
  • Serve events carry serveCollectives when serve allows at least one collective.
  • A bulk cancel sends one event carrying the count.
  • access integration ceiling / revoke --server send no integration-<id> name, and access group add-member / remove-member --server send no group name. A test asserts no delegation id appears in any serve telemetry payload, and an integration id appears only as integrationId.
  • 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.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 6 MOREREVIEW+ 14 MOREPR_LINKED+ 2 MORESESSION_SUMMARIZED

Shipped

11/12/2026, 9:54:56 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
skunk-ape assigned skunk-ape11/12/2026, 7:47:47 PM

Sign in to post a ripple.