Repository navigation
feat: error tracking for api, admin and app (CLEAN-218) - #182
Merged
Merged
Conversation
Failures in the API and in both consoles reach nobody today: they stay in the pod log and in the user's browser console. The spec asks for them to be reported to the team's GlitchTip, one project each, with main-site's rule set: expected errors stay out, server failures and unknown errors go in labelled with status and error code, private data is removed first. Only the Ranch production reports; the Mazda fork inherits the code and stays silent because no destination is committed. The plan, the two contracts and the research record how one rule set is shared by three projects that cannot import from each other, and what was verified against a local stand-in for the tracker.
@sentry/bun for the API, which runs under Bun in production, and @sentry/vue for the two consoles, which are SPAs. The 10.x line, the one main-site already runs against the same GlitchTip; 11 is out but unproven there. The lockfile was written by Bun 1.4.4, the version the Dockerfiles pin, and only adds entries.
A setup/sentry slice. sentry.rules.ts decides what is reported, labels it and strips private data; it imports nothing, so the same file serves the consoles. Every event passes through it in beforeSend, however it was captured. A global exception filter reports a failed request and then lets Nest answer exactly as before; a filter rather than an interceptor because guards and pipes throw before any interceptor runs. The error-handling interceptor keeps the original error as the cause of the 500 it builds, so the tracker gets the real stack. The two process handlers in main.ts report beside their existing log line, and twelve catch blocks that log and carry on now report too, deploy and the knowledge jobs among them. Off unless the process runs from a built image (RANCH_VERSION baked in, not NODE_ENV: the live API runs with NODE_ENV=dev) and SENTRY_DSN is set; otherwise the SDK is not even loaded. The SDK's own uncaught-exception handlers are left out because the first one exits the process, and the Kubernetes watch timeout that main.ts already swallows is ignored by rule. Request bodies and cookies are never attached, the user is an opaque id, and the operation is the route pattern, never the URL.
…218) The same setup/sentry slice in both consoles, file for file, built around the same sentry.rules.ts the API carries. handleError gains one call at its end, where main-site has it, so the toast, the redirect to sign-in and the dev logging are untouched; errors the browser raises by itself take the same rules in beforeSend. Events carry the screen as a route pattern and the signed-in user as an id, cleared on sign-out. The SDK is downloaded only when a production build has NUXT_PUBLIC_SENTRY_DSN set at runtime; nuxt dev and a build without it never fetch it. ErrorMapper keeps the client's ERR_NETWORK or ERR_CANCELED code on a request that got no answer: such a request has no status and was mapped to 500, which would have reported every dropped connection as a server failure. scripts/sentry-twin.test.ts fails CI when the three copies of the rules differ, when the two console slices differ, or when a real DSN appears anywhere in the repository. Twin check: both consoles were changed identically, in the sentry slice and in the two setup/error files.
…(CLEAN-218) The api, admin and app deployments read their DSN from a key of the ranch-error-tracking secret, referenced as optional in all five manifests. The values live in the cluster and never in this repository, so a cluster without the secret starts as before and reports nothing, and a fork that merges these manifests does not start reporting to our tracker.
An operations page for whoever turns reporting on for an installation: what is and is not reported, what never leaves, the one secret and its three keys, how to check it works and how to turn it off. CLAUDE.md gains the rule that sentry.rules.ts is edited in the API and copied to both consoles in the same commit, and that a DSN is never written into a file, a ticket or a PR.
…EAN-218) The rules filtered headers, addresses, extra and contexts but sent an exception's own message as written, and in Ranch that text can quote what the failing code held: a database URL with its password, a share link with its token, an upstream answer echoing a Bearer header, a person's email. scrubText now runs over the event message, every exception in the chain and breadcrumb messages, and masks URL user-info, sensitive query parameters, Bearer and Basic values, key=value credentials, sk- provider keys and emails. Ordinary messages come through unchanged. Raised by the automated security review of the first push; the three copies of sentry.rules.ts change together.
…turned on (CLEAN-218) The release workflow restarts the deployments but does not apply manifests. ArgoCD syncs k8s/platform from main; k8s/deploy is applied by hand. The operations page now says so, and how to check that a deployment carries the reference.
…off (CLEAN-218) Two holes in the text masking added one commit ago. The user-info of a URL was masked up to the first /, #, ? or @, so a password holding one of those kept its tail; it is now everything up to the last @. And the SDK cuts a long message and appends ... before the rules see it, so a database URL cut before its @ went out with half a password; a cut-off tail that looks like an address or an assignment is now masked whole. Raised by the automated security review. The three copies of sentry.rules.ts change together.
The pattern that masked a cut-off tail was unanchored over runs of non-space characters, so a long message with no spaces made it backtrack, and it runs on the request path. The tail is now found by walking back from the end, and any text is cut to 2048 characters before a pattern touches it. Raised by the automated security review. The three copies of sentry.rules.ts change together.
This was referenced Nov 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Ticket: CLEAN-218
A failure in the API or in a console reaches nobody today: it stays in the pod log and in the user's browser. This reports unexpected failures from
api,adminandappto our GlitchTip, each to its own project, with main-site's rule set.It ships switched off. No destination is in the repository. Nothing reports until three DSNs are put into a cluster secret, which is a separate step after the release. The Mazda fork gets this code through a catch-up merge and stays silent.
What is in
sentry.rules.tsdecides what is reported, labels it and strips private data. It exists three times, byte for byte, inapi,adminandapp, and imports nothing. Every event passes through it inbeforeSend, however it was captured.main.tsreport beside their log line. Twelve catch blocks that log and carry on now report too.handleError. The SDK is downloaded only when a production build has a DSN at runtime.statusCodeanderrorCode. Also out: the user's own network, a stale tab asking for a removed chunk, the Kubernetes watch timeoutmain.tsalready swallows, and everything in local development.ranch-error-tracking, with a key per project, referenced from all five manifests.docs/operations/error-tracking.mdis the operator's page.Two things a reviewer should know
NODE_ENV.k8s/deploy/30-api.yamlruns the production API withNODE_ENV: "dev". The gate is "runs from a built image":RANCH_VERSIONset and notdev.ErrorMapperchanged in both consoles. A request that got no answer has no status and was mapped to 500; it now keeps the client'sERR_NETWORK/ERR_CANCELEDcode, so a dropped connection is not reported as a server failure. Status, message and toast are as before.Twin consoles
Both consoles were changed, identically: the new
setup/sentryslice is the same directory inadminandapp, and the edits tosetup/error(error.service.ts,error.mapper.ts) are the same in both.scripts/sentry-twin.test.tsnow fails CI if the slices or the three rules files drift, or if a real DSN appears anywhere in the repository.Background sites wired
chat.insight,chat.sync,reins.index-reconcile,reins.extraction(2),reins.migration(2),reins.provision,reins.indexing,agent.deploy,reins.archive-import,paddock.evaluation,integration.extension-archive.agentEvent.ingest.controllerkeeps the original error as the cause of its 500.Left alone, with the reason, in
specs/029-error-tracking/research.mdR6: sites that rethrow, MCP handlers that answer the caller, the SSE ping to a closed connection, and the two per-knowledge retries inindexReconcile, which run on a 60-second tick and would send an event a minute per knowledge base while LightRAG is down.Gates run
cd api && npx jestcd api && bun run buildeslinton every API file touchedbun run test:scriptsnpx nuxt typecheckinadminand inappbun test slicesinadmin/appbun run locale:check,bun run i18n:checkChecked by running it, against a local HTTP server standing in for the tracker (our GlitchTip was not touched):
NODE_ENV=dev: three of six captures arrive, a 404, a 401 and the watch timeout do not; no session envelope; with the tracker unreachable nothing throws and the calls return in 5 ms.adminin a browser, production build with a DSN set at runtime: a component error, a 503 and an uncaught timer error arrive; a 400, anERR_NETWORK, a rejected 401 and a stale chunk do not;?token=in the address arrives as[Filtered].adminproduction build without a DSN, andnuxt devwith one: nothing sent, SDK not downloaded.Not in this PR
appwas not opened in a browser; its slice is byte-identical toadmin's and its typecheck and tests pass.