Documentation

install once, track page views and server events in the same dashboard

Quick start

Script tag (recommended)

Add this to your page <head>. Page views are tracked automatically.

<script src="https://api.loggerlizard.com/js/lizard.js"
        data-api-key="llz_pub_YOUR_KEY"></script>

data-project is no longer needed. It is still accepted for older installs but does nothing you need.

npm

npm install @loggerlizard/lizard

import Lizard from '@loggerlizard/lizard';

const liz = new Lizard('llz_pub_YOUR_KEY', { autoTrack: true });

Tracking events

liz.log('event_name', { any: 'metadata' }) is the primary method.

liz.log('signup', { plan: 'pro' });
liz.log('purchase', { amount: 19, currency: 'gbp' });

With the script tag, window.lizard.log(...) works anywhere. window.lizard.track(...) is an alias kept for compatibility.

Auto-tracked events

When autoTrack is on, LoggerLizard records these for you.

event	when
page_view	on load, and on route changes when `trackSpaNavigation` is on
button_click	a button is clicked
link_click	a link is clicked
form_submit	a form is submitted
page_hide, page_show	the tab is hidden or shown

Configuration

Pass options as the second argument to new Lizard(key, options).

option	default	what it does
autoTrack	false	Track page views, clicks and form submits automatically.
trackSpaNavigation	false	Fire a page_view on client-side route changes.
batchInterval	5000	Milliseconds to buffer events before sending a batch.
debug	false	Log SDK activity to the console.

How failures behave

Analytics should never add latency, break your site, or spam your users. LoggerLizard fails safely.

Invalid key or blocked domain: the SDK disables itself for the rest of the page load after a single console warning. No retry spam.
Rate limited: it reads the Retry-After header and backs off until then.
Offline: events queue in the browser and send when the connection returns.
Server errors: three retries with exponential backoff, then that batch is dropped and tracking continues.
Bots and headless browsers: automated browsers are never tracked client-side, and known crawlers are flagged server-side and left out of your stats and your quota.

Server-side events

Every project also has a secret key (it starts with llz_sec_) that skips domain checks, for sending events from any backend. Keep it in an environment variable, never in client code or committed files.

Send an event with one fetch. This fire-and-forget helper never throws, never retries, and is a no-op until LIZARD_SECRET_KEY is set.

export function lizard(event, metadata, duration_ms, status) {
  const key = process.env.LIZARD_SECRET_KEY;
  if (!key) return; // no-op until configured

  void fetch('https://api.loggerlizard.com/log', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-API-Key': key },
    body: JSON.stringify({ event, metadata, duration_ms, status }),
    signal: AbortSignal.timeout(3000),
  }).catch(() => {});
}

Server events appear in the same dashboard tagged server, skip geolocation, and support duration_ms and status (ok or error) for health tracking.

lizard('audit_run', { site: 'example.com' }, 1240, 'ok');
lizard('audit_failed', { site: 'example.com' }, 320, 'error');

Domains

Public keys only send from domains you whitelist in project settings. localhost always works for development, so you can integrate before you deploy.

Start free View live demo