Monitoring: Error Tracking with Sentry
Relevant source files
The following files were used as context for generating this wiki page:
The llama-leaks frontend application integrates Sentry for comprehensive error tracking and performance monitoring. This system is designed to automatically capture unhandled JavaScript exceptions, track application performance across different routes, and provide developers with tools for manual event reporting.
The integration is established at the application's root, ensuring that all components and pages are monitored. Key aspects include a global error boundary, automatic instrumentation of routing via a Higher-Order Component, a centralized utility module for Sentry APIs, and a dedicated testing mechanism for development environments.
Core Integration & Configuration
The foundation of Sentry monitoring is established in the main App.tsx component and configured through project dependencies.
Sources: frontend/src/App.tsx, frontend/package.json
Dependencies
The project utilizes the following Sentry packages for its frontend monitoring:
| Package | Version | Purpose |
|---|---|---|
@sentry/react | ^9.33.0 | The main Sentry SDK for React applications, providing error boundaries and hooks. |
@sentry/vite-plugin | ^3.5.0 | A Vite plugin likely used for uploading source maps to Sentry during the build process. |
Sources: frontend/package.json:28-29
Application Root Setup
Sentry is integrated at the highest level of the component tree in App.tsx to ensure complete coverage. This is achieved through two primary mechanisms: an error boundary and a routed component wrapper.
- Error Boundary: The entire application is wrapped in a
<Sentry.ErrorBoundary>. This component automatically catches JavaScript errors that occur in its child component tree, preventing the app from crashing and reporting the errors to Sentry. - Fallback UI: A custom
ErrorFallbackcomponent is provided to the error boundary. If an unhandled error is caught, this UI is rendered, informing the user of the issue and providing options to "Try again" or navigate to the homepage. - Route Tracking: The
BrowserRouterfromreact-router-domis wrapped withSentry.withSentryReactRouterV6Routing. This creates a Higher-Order Component (SentryBrowserRouter) that automatically instruments the application's routes for performance monitoring, tracking page loads and navigation events as transactions in Sentry.
The following diagram illustrates the component hierarchy and the Sentry integration points within App.tsx.
This diagram shows how Sentry's Error Boundary wraps the entire application component tree to capture unhandled exceptions.
Sources: frontend/src/App.tsx:1-62
A snippet of the implementation in App.tsx:
// frontend/src/App.tsx:50-61
const App = () => (
<Sentry.ErrorBoundary fallback={<ErrorFallback />} showDialog>
<QueryClientProvider client={queryClient}>
<ThemeProvider defaultTheme="dark" storageKey="vite-ui-theme">
<SentryBrowserRouter>
<Routes>
{/* ... routes ... */}
</Routes>
</SentryBrowserRouter>
</ThemeProvider>
</QueryClientProvider>
</Sentry.ErrorBoundary>
);
Sources: frontend/src/App.tsx:50-61
Sentry Utility Module (sentry.ts)
To standardize interactions with the Sentry SDK and provide a clean, reusable API, the project includes a dedicated utility module at frontend/src/utils/sentry.ts. This module exports several wrapper functions for common Sentry operations.
Sources: frontend/src/utils/sentry.ts
Provided Functions
The module offers a set of helpers for manual error and event reporting, context enrichment, and performance tracing.
| Function | Description |
|---|---|
captureException | Manually captures a caught Error object. It allows for additional context to be passed, which is then attached to the event as tags. |
captureMessage | Sends a custom text message to Sentry. The severity level (info, warning, error) can be specified. |
setUserContext | Associates subsequent events with a specific user by setting their ID, email, or username in the Sentry scope. |
setTag | Adds a custom key-value tag to all future Sentry events, which is useful for filtering and segmenting issues. |
startSpan | Programmatically starts a new performance span, allowing for the measurement of custom operations. |
addBreadcrumb | Adds a breadcrumb to the event's context, helping to create a timeline of actions that led up to an error. |
Sources: frontend/src/utils/sentry.ts:1-49
Usage Flow
Components can import these utility functions to report handled errors or other significant events. For example, a try...catch block that handles a failed API call could use captureException to log the error in Sentry without crashing the application.
// Example from frontend/src/components/VersionLeaderboard.tsx
// While not explicitly using Sentry, this is where `captureException` would be called.
try {
// ... fetch logic ...
} catch (err) {
setError(err instanceof Error ? err.message : 'Failed to load leaderboard data');
console.error('Error fetching leaderboard data:', err);
// Sentry call would be added here:
// captureException(err, { component: 'VersionLeaderboard' });
}
Sources: frontend/src/components/VersionLeaderboard.tsx:125-129
The following sequence diagram shows how a component would use the captureException utility to report an error.
This diagram illustrates the flow when a component calls the captureException utility function, which then interacts with the core Sentry SDK.
Sources: frontend/src/utils/sentry.ts:5-14
Development & Testing
To ensure the Sentry integration is working as expected, a test button is available exclusively in the development environment.
Sources: frontend/src/pages/Index.tsx
Conditional Rendering
The SentryTestButton component is loaded lazily and rendered only when the application is running in development mode (process.env.NODE_ENV === 'development'). This is handled within the Index page component. This approach prevents the test utility from being included in the production bundle, optimizing the final build. The component is also wrapped in a React.Suspense boundary to handle the lazy loading.
// frontend/src/pages/Index.tsx:13-16
const SentryTestButton =
process.env.NODE_ENV === "development"
? lazy(() => import("@/components/SentryTestButton"))
: () => null;
Sources: frontend/src/pages/Index.tsx:13-16
Rendering Logic
The following flowchart visualizes the logic for rendering the SentryTestButton on the Index page.
This flow ensures the test button is only present during development.
Sources: frontend/src/pages/Index.tsx:41-47
Summary
The project's Sentry integration provides a robust framework for monitoring the frontend application's stability and performance. Through automatic error capture via the ErrorBoundary, performance tracing with router integration, and a clean API for manual reporting via utils/sentry.ts, developers have comprehensive tools for identifying and diagnosing issues. The inclusion of a development-only test button further streamlines the process of verifying the monitoring setup. This proactive approach to error tracking is essential for maintaining a high-quality user experience.