feat(cloud): control-plane logs to Sentry Logs and searchable ids on API captures (M7 part 1)

Merged
SA
1d ago
+1336-205

What and why

Part 1 of M7. When a cloud workspace box never starts, the API's own lines are the only record, and today they are about 40 unstructured console lines in Vercel runtime logs that nobody can find by workspace. This PR adds one structured logger for control-plane events and sends them to Sentry Logs.

  • packages/trpc/src/lib/control-log: logControl(event, scope, fields). Every record has log.source = "control", cloud_workspace.id, organization.id, and boot.id when a boot exists. The body is the event name. The level is fixed per event. The fields are typed per event (ids, counts, durations, flags, our own enum values). An error enters a record only as its class. The sink also writes one console line with the error object, so Vercel runtime logs keep what they had.
  • 28 events from what provision, wake, restart, sleep, archive, the meter (authorize, attach, settle, release) and the reconcile do today. They replace the 25 console lines that had a workspace and organization at hand. The other 16 stay as console lines; the evidence page lists them and says why.
  • Sentry: a boot.id attribute on the provision and wake transactions after authorizeBoot. Workspace, organization and boot ids become tags instead of extra on the exceptions captured in these files. A new captureException at the three places a workspace is marked failed (provision catch, provision queue failure, markSandboxUnavailable).
  • Volume and refusals (review): wake.started and wake.completed are written only for a wake that boots or resumes a box (the beforeSendTransaction rule), so keepalive wakes write nothing. Autumn refusals are boot.refused at warn: no wake.failed, and in the provision catch workspace.failed is at warn with failure.refused and no exception. The evidence page estimates about 10,000 to 12,000 records a day, about 0.3 GB a month.
  • enableLogs: true in apps/api/sentry.server.config.ts. This is already the default in @sentry/core 10.75.2; setting it means a later SDK default change cannot turn logs off.

Part 2 (boot phases and trace id on the boot row) waits for the M4 migration and is not in this PR.

What breaks, for whom

Nothing for released clients: no tRPC procedure input or output changed. Status writes, metering and billing calls are unchanged. The verify-sandbox-asleep model check passes, and the broken config still fails as it should. Some internal signatures in packages/trpc changed: releaseBoot(bootId, reason), queueProvision(job, organizationId), reapWorkspaceFiles(id, organizationId), and queueReap's box argument now includes organizationId.

Records reach Sentry only where Sentry is enabled (production). Whether our Sentry plan includes Logs, and their retention, has not been confirmed yet.

Evidence

Checks

  • packages/trpc: bun test: 1007 pass, 0 fail; bun run typecheck: exit 0
  • apps/api: bun run typecheck: exit 0
  • biome check on the changed files: clean
  • .agents/skills/verify-sandbox-asleep/run.sh: "No error has been found"

Summary by cubic

Adds a structured control-plane logger and sends cloud workspace events to Sentry Logs, so a workspace that never boots is traceable by workspace, organization, and boot id. Replaces 28 console lines in cloud-workspace with typed events (level fixed per event, fields limited to ids, counts, durations, flags, and enum values) while keeping each error object on the same console line. Also moves workspace/organization/boot ids from extra to tags on captured exceptions in these files, and captures an exception at the three places a workspace is marked failed. Sets enableLogs: true in the API Sentry config.

  • Workspace, organization, and boot ids become searchable tags; boot.id is also set as an attribute on provision and wake transactions.
  • Autumn usage refusals are expected states: boot.refused and the provision workspace.failed log at warn with no exception capture, and the session is counted separately.
  • A wake that only keeps a serving box alive writes no record; workspace.failed and workspace.archived are captured only when the row actually moved.
  • No procedure inputs or outputs, status writes, metering, or billing calls change. A few internal packages/trpc signatures take new arguments: releaseBoot(bootId, reason), queueProvision(job, organizationId), reapWorkspaceFiles(id, organizationId), and queueReap's box now includes organizationId.
  • Records reach Sentry Logs only where Sentry is enabled (production); whether the Sentry plan includes Logs and their retention is not yet confirmed.

Summary by CodeRabbit

  • Improvements
    • Cloud workspace lifecycle events—including provisioning, wake and sleep, metering, and cleanup—now have more consistent status and failure records.
    • Workspace and organization context is included in relevant error reports, while sensitive error messages are excluded from serialized event records.
    • Provisioning and boot-release outcomes are recorded with additional details, including failure site and whether the workspace state changed.