Skip to main content

Sentry

NearSync integrates with Sentry for error tracking and performance monitoring across all three platform apps: the admin dashboard, client portal, and marketing website. Errors are captured automatically, enriched with context, and reported to a centralized Sentry dashboard where they can be triaged and resolved.

How Errors Are Captured​

The integration is built into the @nearsync/monitoring package, which provides three main utilities:

Initialization​

Each app initializes Sentry once at startup (in its entry point) with:

  • The app name (admin-dashboard, client-portal, or marketing-website) used to tag all events for filtering
  • The environment (development, staging, or production)
  • The release version for tracking which deployment introduced a regression

If no Sentry DSN is configured (common in local development), initialization is a no-op and the app runs normally without error tracking.

Automatic Error Capture​

Once initialized, Sentry automatically captures:

  • Unhandled exceptions -- JavaScript errors that bubble up without being caught
  • Unhandled promise rejections -- Async errors that are not caught by .catch() handlers
  • Performance traces -- Sampled transaction traces for monitoring response times (configurable sample rate, defaulting to 10%)
  • Session replays -- On errors, Sentry captures a replay of the user's session leading up to the error (100% of error sessions are replayed; normal sessions are not recorded)

Noise Filtering​

Not every browser error is actionable. The integration filters out known non-issues before they reach Sentry:

  • ResizeObserver loop errors -- A benign browser quirk that does not affect functionality
  • Browser extension errors -- Errors originating from Chrome or Firefox extensions, not from NearSync code
  • Ad blocker interference -- Network errors caused by ad blockers intercepting analytics requests

This keeps the Sentry dashboard focused on real application issues.

SentryErrorBoundary Component​

The SentryErrorBoundary component wraps React component trees to catch rendering errors gracefully. When a component inside the boundary throws during render:

  1. Sentry captures the error with full stack trace and component context
  2. The boundary renders a styled fallback UI instead of crashing the entire page
  3. The fallback shows a message like "Sales HQ encountered an error" (using the module name) with a "Try Again" button that re-renders the component tree
  4. The error is tagged with the module name for easy filtering in the Sentry dashboard

Each HQ module in the admin dashboard is wrapped in its own SentryErrorBoundary, so an error in one module does not take down the rest of the application.

Error Context Enrichment​

When errors are captured manually (in catch blocks or service layers), the captureError utility attaches structured context:

  • Module -- Which HQ module the error occurred in (e.g., "finance", "comms", "ai")
  • Action -- What operation was being attempted (e.g., "createInvoice", "sendWhatsApp")
  • User ID -- The authenticated user who triggered the error
  • Extra data -- Any additional diagnostic information relevant to the error

This context appears in the Sentry dashboard alongside the stack trace, making it faster to reproduce and fix issues.

User Context​

After login, the monitoring package sets the current user on the Sentry scope. Every subsequent error event includes the user's ID, email, and role, so you can identify whether errors are affecting specific users or roles.

Viewing Errors​

Errors from all three NearSync apps flow into the Sentry dashboard. You can filter and search by:

  • App tag -- Filter to just admin-dashboard, client-portal, or marketing-website errors
  • Module tag -- Filter to errors from a specific HQ module
  • Environment -- Separate development, staging, and production errors
  • Release -- See which deployment introduced new errors
  • User -- Find all errors affecting a specific user

Sentry's issue grouping automatically deduplicates identical errors, so you see one issue entry with a count rather than thousands of individual events.

Configuration​

Credentials Required​

  • Sentry DSN -- A project-specific Data Source Name that tells the SDK where to send events. This is a URL provided by Sentry when you create a project. It is safe to include in client-side code (it only allows sending events, not reading them).

For Managed deployments, NearSync configures the Sentry DSN. For BYOK deployments, you can optionally provide your own Sentry DSN to receive error reports in your own Sentry organization, or omit it to run without error tracking.

Sample Rates​

The default configuration uses:

  • Traces sample rate: 10% of transactions are traced for performance monitoring
  • Session replay on error: 100% of sessions that encounter an error include a replay
  • Session replay (normal): 0% of normal sessions are recorded (privacy-conscious default)

These rates can be adjusted per-app if needed.

If Sentry Is Unavailable​

Sentry being unavailable has zero impact on application functionality. Error tracking is a fire-and-forget operation. If the Sentry servers are unreachable, error events are silently dropped and the application continues running normally. No user-facing features depend on Sentry.