How to Set Up Error Tracking with Gurulu

Most analytics platforms stop at pageviews and clicks. Gurulu goes further by capturing unhandled exceptions, promise rejections, and network errors alongside your analytics data. This guide walks you through setting up error tracking from scratch.

Why Track Errors in Your Analytics Platform?

When errors live in a separate tool, you lose context. You know a user saw an error, but you do not know what they did before or after. Gurulu correlates errors with the full session timeline -- pageviews, clicks, form submissions -- so you can see exactly what led to the crash and whether the user recovered or bounced.

Step 1: Add the Error Tracking Script

If you already have the main t.js tracker installed, error tracking is already active by default. Gurulu automatically captures window.onerror and unhandledrejection events.

For advanced error tracking with stack trace deobfuscation, add the dedicated error script:

<script
  src="https://cdn.gurulu.io/t-errors.js"
  data-site-id="YOUR_SITE_ID"
  data-token="YOUR_TOKEN"
  async
></script>

Or via the npm package:

import { initErrors } from '@gurulu/tracker';

initErrors({
  siteId: 'YOUR_SITE_ID',
  token: 'YOUR_TOKEN',
  captureConsole: true,   // optional: capture console.error
  captureNetwork: true,   // optional: capture failed fetch/XHR
});

Step 2: Upload Source Maps

Production bundles are minified, which makes stack traces unreadable. Gurulu supports source map uploads so you see original file names, line numbers, and function names.

Use the CLI to upload source maps as part of your build pipeline:

npx @gurulu/cli sourcemaps upload \
  --site-id YOUR_SITE_ID \
  --release v1.2.0 \
  --directory ./dist

Source maps are stored securely and never exposed to end users. You can also configure automatic uploads in CI by setting the GURULU_TOKEN environment variable.

Step 3: View Errors in the Dashboard

Navigate to the Errors tab in your dashboard. You will see errors grouped by fingerprint -- similar stack traces are collapsed into a single issue. For each issue you get:

• Error count and affected users -- how widespread the issue is
• First and last seen -- when it appeared and whether it is still active
• Stack trace -- deobfuscated if source maps are uploaded
• Session replay link -- jump to the user session where the error occurred
• Browser and OS breakdown -- identify environment-specific bugs

Step 4: Set Up Alerts

Gurulu can notify you when a new error type appears or when an existing error spikes. Go to Settings > Alerts and create a rule. You can route alerts to Slack, email, or any webhook endpoint.

Tips for Effective Error Tracking

Tag releases. Always pass a release identifier so you can filter errors by deployment and quickly see if a new release introduced regressions.

Add context. Use gurulu.setUser() to attach user identity to errors. This makes it easy to see which customers are affected and reach out proactively.

Monitor network errors. Enable captureNetwork to catch failed API calls. These are often the root cause behind blank screens and broken UIs.