Sentry Integration Patterns Overview Implement error tracking and performance monitoring using Sentry following the project's established patterns for both client and server. When to Use This Skill Configuring Sentry SDK Adding error tracking to TRPC procedures Implementing custom spans/traces Setting up user context Working with Sentry API SDK Configuration Server-side // apps/web-app/src/server.ts import * as Sentry from "@sentry/tanstackstart-react" ; Sentry . init ( { ... ( env . SENTRY_DSN && { dsn : env . SENTRY_DSN } ) , sendDefaultPii : true , environment : env . ENVIRONMENT , release : env . VERSION , dist : "server" , spotlight : isDev , // Local dev debugging enableLogs : true , tracesSampleRate : isDev ? 1.0 : 0.001 , profilesSampleRate : isDev ? 1.0 : 0.001 , profileLifecycle : "trace" , integrations : [ Sentry . postgresIntegration ( ) , Sentry . redisIntegration ( ) , Sentry . httpIntegration ( ) , ] , ignoreTransactions : [ "/api/alive" , "/api/health" ] , beforeSend ( event , hint ) { // Filter AbortError completely if ( error instanceof DOMException && error . name === "AbortError" ) { return null ; } // Mark expected TRPC errors as handled return markExpectedTRPCErrorInEvent ( event , error ) ; } , } ) ; Client-side // apps/web-app/src/client.tsx Sentry . init ( { ... ( env . VITE_SENTRY_DSN && { dsn : env . VITE_SENTRY_DSN } ) , sendDefaultPii : true , environment : env . VITE_ENVIRONMENT , release : env . VITE_VERSION , dist : "client" , spotlight : isDev , integrations : [ Sentry . tanstackRouterBrowserTracingIntegration ( router ) , Sentry . replayIntegration ( ) , Sentry . feedbackIntegration ( { colorScheme : "system" , autoInject : false , } ) , ... ( isDev ? [ Sentry . spotlightBrowserIntegration ( ) ] : [ ] ) , ] , tracesSampleRate : isDev ? 1.0 : 0.001 , replaysSessionSampleRate : 0.1 , replaysOnErrorSampleRate : 1.0 , beforeSend ( event , hint ) { return markExpectedTRPCErrorInEvent ( event , hint . originalException ) ; } , } ) ; TRPC Middleware // apps/web-app/src/infrastructure/trpc/init.ts export const sentryMiddleware = t . middleware ( Sentry . trpcMiddleware ( { attachRpcInput : true , } ) ) ; // Used in procedure chain export const publicProcedure = t . procedure . use ( debugMiddleware ) . use ( sentryMiddleware ) ; Server Function Middleware // apps/web-app/src/infrastructure/middleware/sentry-function-middleware.ts export const sentryFunctionMiddleware = createMiddleware ( { type : "function" , } ) . client ( async ( { next , serverFnMeta } ) => { // Client-side timing and error logging } ) . server ( async ( { next , data , serverFnMeta } ) => { return Sentry . startSpan ( { op : "function.server" , name : functionName , attributes : { hasData : data !== undefined , functionName , } , } , async ( span ) => { try { const result = await next ( ) ; span . setStatus ( { code : 1 } ) ; // OK return result ; } catch ( error ) { captureException ( error ) ; span . setStatus ( { code : 2 } ) ; // ERROR throw error ; } } ) ; } ) ; Error Capture Patterns Expected TRPC Error Codes // From apps/web-app/src/infrastructure/errors.ts const EXPECTED_TRPC_CODES = [ "NOT_FOUND" , "FORBIDDEN" , "UNAUTHORIZED" , "BAD_REQUEST" , ] ; Custom Capture Helper // apps/web-app/src/infrastructure/sentry-utils.ts export function captureException ( error : unknown , captureContext ? : Sentry . CaptureContext ) { if ( isExpectedTRPCError ( error ) ) { Sentry . withScope ( ( scope ) => { scope . setLevel ( "warning" ) ; scope . setTag ( "error.expected" , "true" ) ; Sentry . captureException ( error , { mechanism : { type : "generic" , handled : true } , } ) ; } ) ; } else { Sentry . captureException ( error , captureContext ) ; } } beforeSend Helper export function markExpectedTRPCErrorInEvent ( event : Sentry . ErrorEvent , error : unknown ) { if ( ! isExpectedTRPCError ( error ) ) return event ; event . exception ?. values ?. forEach ( ( exception ) => { exception . mechanism = { type : "generic" , handled : true , } ; } ) ; event . level = "warning" ; event . tags = { ... event . tags , "error.expected" : "true" } ; return event ; } Database Query Tracing Manual Tracing // apps/web-app/src/infrastructure/db/tracing.ts export async function traced < T
( query : DrizzleQuery , operationName ? : string ) : Promise < T
{ return Sentry . startSpan ( { op : "db.query" , name : sqlString , attributes : { "db.system" : "postgresql" } , } , ( ) => query as Promise < T
) ; } // Usage: const users = await traced ( db . select ( ) . from ( usersTable ) . where ( eq ( usersTable . id , userId ) ) ) ; Automatic Proxy Tracing // apps/web-app/src/infrastructure/db/traced-db.ts export function createTracedDb ( db : Db ) : Db { return new Proxy ( db , { get ( target , prop ) { if ( [ "select" , "insert" , "update" , "delete" ] . includes ( String ( prop ) ) ) { return function ( ... args ) { const queryBuilder = originalMethod . call ( target , ... args ) ; return createTracedQueryBuilder ( queryBuilder , String ( prop ) ) ; } ; } return originalMethod ; } , } ) ; } User Context Hook // apps/web-app/src/hooks/use-set-sentry-context.ts export function useSetSentryContext ( ) { const { session } = Route . useRouteContext ( ) ; useLayoutEffect ( ( ) => { if ( session ?. user ) { Sentry . setUser ( { id : session . user . id , email : session . user . email , username : session . user . name , } ) ; } else { Sentry . setUser ( null ) ; } } , [ session ] ) ; } Sentry API Service (Effect-based) Error Types // packages/services/src/sentry/errors.ts export class SentryApiError extends Schema . TaggedError < SentryApiError
( ) ( "SentryApiError" , { statusCode : Schema . Number , body : Schema . String , url : Schema . String , } ) { } export class SentryRateLimitError extends Schema . TaggedError < SentryRateLimitError
( ) ( "SentryRateLimitError" , { retryAfter : Schema . Number , message : Schema . String , } ) { } Service Pattern // packages/services/src/sentry/sentry-issues.ts export class SentryIssuesService extends Context . Tag ( "@project/SentryIssuesService" ) < SentryIssuesService , { readonly getNewErrors : ( params ) => Effect . Effect < SentryIssuesResponse , SentryError
; readonly getRegressions : ( params ) => Effect . Effect < SentryIssuesResponse , SentryError
; readonly verifyToken : ( params ) => Effect . Effect < SentryOrganization [ ] , SentryError
; readonly listProjects : ( params ) => Effect . Effect < SentryProject [ ] , SentryError
; }
( ) { static readonly layer = Layer . effect ( SentryIssuesService , Effect . gen ( function * ( ) { const httpClient = yield * HttpClient . HttpClient ; // ... service implementation } ) ) ; } // Live layer export const SentryIssuesServiceLive = SentryIssuesService . layer . pipe ( Layer . provide ( FetchHttpClient . layer ) ) ; API Client with Retry const retryPolicy = Schedule . exponential ( "500 millis" ) . pipe ( Schedule . compose ( Schedule . recurs ( 2 ) ) ) ; export const sentryRequest = < A , I
( httpClient : HttpClient . HttpClient , schema : Schema . Schema < A , I
, params : SentryRequestParams ) : Effect . Effect < { data : A ; nextCursor : string | null } , SentryApiError | SentryRateLimitError
=> Effect . fn ( "Sentry.request" ) ( function * ( ) { // Request with Bearer token auth // Rate limit handling (429 -> SentryRateLimitError) // Schema validation // Link header pagination parsing } ) ( ) ; Key Rules Use beforeSend to mark expected errors as handled Filter health check endpoints from transactions Set user context in layout effect for session changes Use startSpan for custom instrumentation Handle rate limits (429) with SentryRateLimitError Different sample rates for dev vs production Include replays for error sessions (100% on error)