Skip to main content

Observability And Error Handling Rule

Observability and explicit error handling are mandatory for Finance App runtime work.

Every backend feature, integration, import flow, authenticated workflow, and meaningful frontend workflow must define how failures are visible, diagnosable, and safe for users.

Required Behavior​

  • Log runtime failures with structured, request-correlated metadata that Cloud Logging can query as JSON.
  • Never log passwords, bearer tokens, uploaded file contents, transaction descriptions, or other personal finance details.
  • Emit bounded Prometheus metrics for backend HTTP requests and material product flows.
  • Propagate or create a request id for every backend response.
  • Include the request id in error responses so UI/support can correlate failures.
  • Normalize user-facing errors instead of exposing raw stack traces or transport internals.
  • Treat 401/403 handling as part of the product flow: clear stale sessions and send users back to login when needed.
  • Async jobs must expose user-visible progress, current step, completion, and fallback/error state through the product API when users can reasonably wait for or return to the work.
  • Voice and AI workflows must log lifecycle metadata only. Do not log raw audio, transcripts, prompts, transaction descriptions, merchant names, model payloads, or generated finance details.
  • Record observability impact and no-delta rationale in the task file.

Minimum Runtime Checklist​

For every runtime change, record:

  1. logs added or intentionally unchanged
  2. metrics added or intentionally unchanged
  3. trace/correlation behavior
  4. user-facing error behavior
  5. sensitive data that must not be logged
  6. validation performed

Current Baseline​

  • GET /ops/metrics exposes Prometheus-compatible metrics.
  • HTTP requests emit request count and duration metrics.
  • Backend responses include x-request-id.
  • Error responses include requestId, statusCode, message, path, and timestamp.
  • Backend request logs are emitted as JSON with event, severity, method, path without query string, bounded route label, status code, duration, request id, and Cloud Run trace context when available.

Documentation Rule​

When observability or error-handling expectations change, update:

  • README.md
  • ONBOARDING.md
  • AGENTS.md
  • CODING_STANDARDS.md
  • docs/workflows/observability-error-handling-rule.md
  • docs-site/docs/architecture/backend.md
  • docs-site/docs/reference/backend-http-surface.md
  • .tasks/INDEX.md and the active task file