Error & Performance Monitoring
Relevant source files
The following files were used as context for generating this wiki page:
Kocteau utilizes a multi-layered monitoring strategy to ensure application stability and recommendation engine efficiency. The system is split into two primary domains: external error tracking and performance instrumentation via Sentry, and internal product health monitoring focused on the "For You" recommendation loop. This approach allows developers to distinguish between technical failures (e.g., JavaScript exceptions) and product failures (e.g., poor recommendation conversion).
Sources: README.md, apps/web/next.config.ts:60-95
Sentry Integration & Error Tracking
The project implements Sentry for automated error reporting and frontend/backend performance tracing. The integration is configured at the build level via next.config.ts, ensuring that source maps are uploaded and the SDK is correctly initialized across the Next.js App Router.
Configuration and Build Integration
The Sentry configuration is centralized in next.config.ts using the withSentryConfig wrapper. Key configurations include:
- Tunneling: Requests are routed through
/monitoringto circumvent ad-blockers. - Source Maps:
widenClientFileUploadis enabled to provide detailed stack traces. - Tree-shaking: Debug logging is automatically removed in production to reduce bundle size.
- Vercel Integration: Automatic instrumentation of Vercel Cron Monitors is enabled.
Sources: apps/web/next.config.ts:60-100
Error Reporting Flow
Errors can be manually triggered and tested via a dedicated example page. This page verifies SDK connectivity and provides a mechanism to throw sample frontend errors.
The diagram shows the lifecycle of a monitored error event, from user interaction to cloud reporting. Sources: apps/web/app/sentry-example-page/page.tsx:48-70
Recommendation Health Monitoring
Beyond technical errors, Kocteau monitors the "Product Loop" through a specialized "Recommendation Health" system. This system tracks how users interact with the "For You" feed and editorial "Starter Picks."
Aggregate Signals
The system tracks several key metrics to determine the health of the recommendation engine:
- Fallback Rate: How often the system resorts to the "latest reviews" feed because the recommendation RPC failed.
- Review Open Rate: The percentage of review impressions that lead to a user opening the full review.
- Starter Conversion: The rate at which curated "Starter Picks" result in a published review by the user.
| Metric | Description | Source File |
|---|---|---|
feed.loads | Total number of times the For You feed was loaded. | metrics.test.ts:13 |
feed.fallbackRate | Percentage of loads resulting in a recommendation fallback. | recommendation-health-summary.tsx:112 |
starter.reviewConversionRate | Rate of published reviews from curated tracks. | recommendation-health-summary.tsx:122 |
tagCoverage | Measures which taste tags are actively represented in the catalog. | recommendation-health-summary.tsx:162 |
Sources: apps/web/components/recommendation-health-summary.tsx:100-130, apps/web/lib/recommendation-health/metrics.test.ts:13-30
Studio Health Dashboard
Internal monitoring is exposed via the /studio/health route. Access is restricted to users with the curator or admin role (verified via getStarterCuratorAccess). The dashboard allows filtering data by time windows (e.g., 7 days, 14 days, 30 days).
The flowchart describes the access control and data fetching logic for the internal health dashboard. Sources: apps/web/app/(main)/studio/health/page.tsx:15-45
Analytics and Event Tracking
The project uses a first-party analytics table in Supabase to track specific product-health events. This avoids surveillance-heavy third-party scripts while providing the data necessary for the Recommendation Health dashboard.
Key events tracked include:
recommendation_fallback: Logged when the recommendation RPC fails.taste_onboarding_completed: Indicates a successful conversion to a "tuned" feed.review_impressionandreview_open: Used to calculate the open rates.starter_review_published: Tracks conversion from curation to user content.
Sources: README.md, apps/web/components/recommendation-health-summary.tsx:120-130
Summary
Error and performance monitoring in Kocteau is a dual-purpose system. Sentry handles technical reliability and performance tracing across the Next.js stack, ensuring the app remains fast and error-free. The Recommendation Health system provides the architectural insight needed to maintain the "Product Truth" of human-led discovery, ensuring that the lightweight algorithms effectively route human taste.
Sources: README.md, apps/web/app/(main)/studio/health/page.tsx:10-15