Automatic Tracking

Once tracelog.init() is called, TraceLog starts capturing user behavior immediately. No additional code is required for any of the events below.

Event Types

page_view

Fires on every page navigation, including SPA route changes. Works with React Router, Next.js App Router, Angular Router, Vue Router, and any router that uses the History API.

Captured data:

• URL (path + query string, sensitive params stripped)
• Page title
• Referrer (previous page or external referrer)
• Navigation timing

session_start

Fires at the beginning of a new browsing session. Sessions expire after 15 minutes of inactivity (configurable via sessionTimeout).

Captured data:

• Session ID (anonymous UUID, cross-tab synchronized)
• Browser name and version
• OS name and version
• Device type (desktop, mobile, tablet)
• Screen resolution
• Referrer
• UTM parameters (source, medium, campaign, term, content)
• Country (resolved server-side from IP, IP is never stored)
• Language (navigator.language)

click

Fires when a user clicks any element. Input values are never captured. Elements marked with data-tlog-ignore are skipped.

Captured data:

• Element tag name (e.g., button, a)
• Element id attribute
• Element class list
• Text content (truncated, PII-redacted)
• Link href (if applicable)
• title, alt, role, and aria-label attributes
• Custom data-* attributes

scroll

Fires periodically as the user scrolls. Tracks engagement depth and speed.

Captured data:

• Scroll depth percentage (0–100%)
• Scroll velocity
• Time spent at depth milestones (25%, 50%, 75%, 100%)

web_vitals

Captures Core Web Vitals once they're available (after page interaction or load). Requires the web-vitals package, which is included as a dependency.

Metric	Description
LCP	Largest Contentful Paint — how fast the main content loads
INP	Interaction to Next Paint — responsiveness to user input
CLS	Cumulative Layout Shift — visual stability
FCP	First Contentful Paint — time until first content appears
TTFB	Time to First Byte — server response time
LONG_TASK	Long tasks blocking the main thread (>50ms)

You can control which Web Vitals are sent using the webVitalsMode configuration option:

await tracelog.init({
  webVitalsMode: 'needs-improvement', // 'all' | 'needs-improvement' | 'poor'
  integrations: {
    tracelog: { projectId: 'your-project-id' }
  }
});

Mode	What gets sent
all	Every Web Vitals report
needs-improvement (default)	Only metrics rated "Needs Improvement" or "Poor"
poor	Only metrics rated "Poor"

Using needs-improvement or poor reduces data volume significantly in production while still surfacing performance problems.

error

Fires when a JavaScript error or unhandled promise rejection occurs.

Captured data:

• Error message (PII-redacted)
• Stack trace (truncated)
• Error type

Sampling: Control what fraction of errors are sent using errorSampling:

await tracelog.init({
  errorSampling: 0.1, // Send 10% of errors (recommended for production)
  integrations: {
    tracelog: { projectId: 'your-project-id' }
  }
});

viewport_visible

Fires when a specific element enters the viewport and stays visible for a minimum dwell time. Requires explicit configuration — not enabled by default.

await tracelog.init({
  viewport: {
    elements: [
      { selector: '.pricing-section', id: 'pricing' },
      { selector: '#cta-hero', id: 'hero-cta' }
    ],
    threshold: 0.5,       // 50% of the element must be visible
    minDwellTime: 1000    // Must stay visible for 1 second
  },
  integrations: {
    tracelog: { projectId: 'your-project-id' }
  }
});

Use this to measure whether users actually see key sections of your page (pricing, CTAs, feature blocks).

Filtering Events

If you use a custom backend and want to exclude high-volume events, use the beforeSend transformer:

tracelog.setTransformer('beforeSend', (event) => {
  if ('type' in event && ['scroll', 'web_vitals'].includes(event.type)) {
    return null; // Excluded from custom backend only
  }
  return event;
});

info

Transformers only apply to custom backend integrations. TraceLog SaaS always receives all events unmodified.

Protecting Sensitive Elements

Prevent TraceLog from capturing interactions with sensitive UI elements using the data-tlog-ignore attribute:

<!-- Nothing inside this element is tracked -->
<div data-tlog-ignore>
  <input type="password">
  <input type="text" name="card_number">
  <button>Pay Now</button>
</div>

See Consent & GDPR for full details on data-tlog-ignore usage.

Tracking Custom Click Events from HTML

Use the data-tlog-name attribute on any element to automatically fire a custom event when that element is clicked — no JavaScript required:

<button data-tlog-name="cta_hero">Start Free Trial</button>

<!-- Optionally include a value -->
<button data-tlog-name="add_to_cart" data-tlog-value="SKU-123">Add to Cart</button>

When clicked, TraceLog fires a custom event with the data-tlog-name as the event name and data-tlog-value (if present) as metadata.