feat(cloud): control-plane logs to Sentry Logs and searchable ids on API captures (M7 part 1)
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 haslog.source = "control",cloud_workspace.id,organization.id, andboot.idwhen 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.idattribute on the provision and wake transactions afterauthorizeBoot. Workspace, organization and boot ids become tags instead ofextraon the exceptions captured in these files. A newcaptureExceptionat the three places a workspace is marked failed (provision catch, provision queue failure,markSandboxUnavailable). - Volume and refusals (review):
wake.startedandwake.completedare written only for a wake that boots or resumes a box (thebeforeSendTransactionrule), so keepalive wakes write nothing. Autumn refusals areboot.refusedat warn: nowake.failed, and in the provision catchworkspace.failedis at warn withfailure.refusedand no exception. The evidence page estimates about 10,000 to 12,000 records a day, about 0.3 GB a month. enableLogs: trueinapps/api/sentry.server.config.ts. This is already the default in@sentry/core10.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
- Evidence page: https://app.superset.sh/page/m7-control-plane-logs-and-sentry-tags-vscgtv (event table, sample records from a test sink and as the real SDK serializes them, tag changes before and after, how secrets are kept out, test output, what was not verified)
- Design: https://app.superset.sh/page/admin-cloud-workspace-cost-and-health-design-8z3d4d
Checks
packages/trpc:bun test: 1007 pass, 0 fail;bun run typecheck: exit 0apps/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.idis also set as an attribute on provision and wake transactions. - Autumn usage refusals are expected states:
boot.refusedand the provisionworkspace.failedlog 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.failedandworkspace.archivedare captured only when the row actually moved. - No procedure inputs or outputs, status writes, metering, or billing calls change. A few internal
packages/trpcsignatures take new arguments:releaseBoot(bootId, reason),queueProvision(job, organizationId),reapWorkspaceFiles(id, organizationId), andqueueReap's box now includesorganizationId. - 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.