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)
• Click coordinates (x, y in viewport pixels)

scroll

Fires periodically as the user scrolls. Tracks scroll depth and direction per container.

Captured data:

• Scroll depth percentage (0–100%)
• Scroll direction (up / down)
• CSS selector of the scrolled container

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

Metrics are buffered per navigation and sent as one consolidated event, not one event per metric:

{
  type: 'web_vitals',
  web_vitals: {
    schema: 'consolidated',
    metrics: [
      { type: 'CLS', value: 0.02 },
      { type: 'FCP', value: 980.42 },
      { type: 'INP', value: 88.7 },
      { type: 'LCP', value: 1450.35 },
      { type: 'TTFB', value: 320.15 }
    ]
  }
}

The event is flushed when the page is hidden or unloaded, or when an SPA route change starts a new navigation. metrics can be partial when a metric never materializes — for example, no INP on a page the visitor never interacted with.

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

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

Mode	What gets sent
all (default)	Every measured value, including good ones
needs-improvement	Only metrics rated "Needs Improvement" or "Poor"
poor	Only metrics rated "Poor"

Leave the default 'all' unless you have a specific reason not to. Consolidation already keeps the volume low, and filtering client-side censors the sample at the source: your dashboard can no longer tell a truncated sample from a complete one, so the good / needs-improvement / poor split and the p75 stop being computable.

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' }
  }
});

Filtering Events at the Project Level

To exclude high-volume event types (click, scroll) from a project, configure excludedEventTypes in the project settings via the TraceLog dashboard. Critical events (session_start, page_view, custom, error, web_vitals) cannot be filtered.

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.