Relationships
#4684 swamp-club: store the integrations each serve reports, and send serve-link events to analytics
Opened by skunk-ape · 11/12/2026· Shipped 11/12/2026
Part of #4459. Sibling swamp issue: #4683 (serve reports its integrations, and its usage events gain a client kind and cover approvals and run control). 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-club's origin/main (6a83c14d):
- Linking is recorded, but only in Mongo.
serve_link_eventsis an append-only history kept 2 years (lib/infrastructure/mongo-serve-link-repository.ts:38). It has requested, approved, denied, approval_refused, report_refused, recorded, emailed, email_failed and ended, each with time, clientId, collective, integrationId and actor (lib/repositories/serve-link-repository.ts:110-133). The only thing that reads it isscripts/serve-link-audit.ts. Nothing inlib/app/serve-linkorroutes/api/v1/servecalls analytics, so there's no funnel (started → approved / denied / refused → ended) and no dashboard. The only analytics trace is apage_viewfor/link. - Link events don't say the platform.
external.platform(e.g.slack) is on the request and link documents but not onserve_link_events, and requests are deleted after 7 days. - We can't see integrations being added.
serve_instancesstores collectives, hostname, version, mode and tags (lib/domain/serve-instance/serve-instance.ts), with no integrations. swamp-club first learns an integration's id and name when its first link starts.
Proposed change
- Store reported integrations. Accept the integrations a serve sends at registration and on change (sibling swamp issue): id, state, createdAt, revokedAt, kept on the serve instance. Unknown or missing fields from older serves are fine. Ids only; no names. Keep a history of state changes so added / revoked counts over time can be queried.
- Link events to analytics. In
recordLinkEvent(lib/app/serve-link/link-events.ts), also send a reliable analytics eventserve_link_<kind>with clientId, collectiveId, integrationId, platform and the actor as distinct id. Leave out the external identity (team, user id, display name, workspace, email), and anything kept from requests that get deleted. Erasure and account merge must cover the analytics events the way they coverserve_link_eventstoday. Check whether the analytics pipeline's erasure already does. platformon link events. Add it toServeLinkEventand set it at each emit site.- Ingest and docs. Make sure telemetry ingest keeps serve's new
clientand collective properties from the sibling issue, and document them incontent/manual/reference/usage-telemetry-events.md, with the new serve-link analytics events wherever internal events are listed.
Done when
- A serve that reports integrations has them stored with state and dates. Revoking one records the change. A serve that reports none, or an older serve, registers as today.
- Every link event kind also lands in analytics as
serve_link_<kind>, with clientId, collectiveId, integrationId, platform and actor, and no external identity. Tests cover each kind, and that a failed analytics send doesn't fail the link action. serve_link_eventsrows carryplatform.- Erasure and merge cover the new analytics events.
- The usage telemetry reference documents the new serve properties.
Out of scope
Building dashboards on the data. Changes to serve, which are in the sibling issue. Sending integration names or external identities anywhere.
Shipped
Click a lifecycle step above to view its details.
system commented 11/12/2026, 7:36:49 PM
Classified automatically when this issue was filed.
- Source: Swamp Club
If you feel this classification is incorrect, add a ripple to tell us so.
Sign in to post a ripple.