Skip to main content

Troubleshooting

Common issues and how to resolve them.

Events not appearing in the dashboard​

  • Check init() was called with the correct projectId. Verify in Project Settings > General that the ID matches.
  • Inspect network requests in DevTools: open Network tab, filter by collect or tracelog, and confirm requests are being sent with a 200 response.
  • Check for ad blockers -- ad blockers can prevent requests to third-party analytics domains. Try disabling your ad blocker, or set up first-party tracking via CNAME.
  • Verify user consent -- if your consent flow prevents init() from being called, no events will be tracked. Check that consent is granted before initialization.

Duplicate events​

  • Don't call init() multiple times. Use tracelog.isInitialized() to guard against re-initialization in SPAs: 
    if (!tracelog.isInitialized()) {
      await tracelog.init({ /* ... */ });
    }
  • Check for multiple script tags loading the TraceLog library. Only include one <script> tag or one import statement.

Session ID keeps changing​

  • Check sessionTimeout config -- the default is 15 minutes of inactivity. If your users have longer idle periods, increase it.
  • Cross-tab sync requires the same origin. Sessions are not shared across different domains or subdomains.

Custom events not tracked​

  • Custom events must be sent after init() has been called. Events fired before initialization are silently dropped.
  • Rate limit: custom events are limited to 60 per minute per event name. If you exceed this, events are silently dropped.
  • Use QA mode to debug: append ?tlog_mode=qa to your page URL, then check the browser console for detailed logs of every captured event.

Ad blockers blocking requests​

Ad blockers target known analytics domains. Set up first-party tracking via CNAME with a CNAME subdomain to route requests through your own domain.

SPA route changes not tracked​

TraceLog auto-detects route changes via the History API (pushState, replaceState). If you use a custom routing mechanism that does not call history.pushState, TraceLog will not detect the navigation. Ensure your router uses the standard History API.

Web Vitals not showing​

  • Check webVitalsMode config -- the default is 'needs-improvement', which only sends metrics rated "Needs Improvement" or "Poor". If set to 'poor', only metrics exceeding the "poor" threshold are captured. Try 'all' to see everything.
  • Some metrics require user interaction: INP (Interaction to Next Paint) only fires after the user interacts with the page.
  • TTFB and FCP are only measured on the initial page load, not on SPA navigations.

Pre-Production Checklist​

Before deploying TraceLog to production, verify the following:

  • Consent flow implemented -- init() only called after user grants analytics consent
  • data-tlog-ignore added to sensitive UI elements (password fields, payment forms)
  • No PII (emails, phone numbers, addresses) in custom event metadata
  • sensitiveQueryParams configured for any app-specific URL parameters
  • allowHttp: false in production (HTTPS only)
  • Event listeners cleaned up on unmount (tracelog.destroy())
  • QA mode tested -- ?tlog_mode=qa shows expected events in console
  • Network requests verified -- events appear in DevTools Network tab
  • Privacy policy updated to disclose analytics data collection