Event Debugger

The Event Debugger polls recent events flowing into your project. Use it to verify your tracking implementation, debug missing properties, and confirm event IDs covered by an ingest receipt are visible in the analytics query path.

Accessing the debugger

Navigate to /{projectId}/debugger in the dashboard app, or click Event Debugger in the sidebar under Tools.

Features

How it works

The debugger polls the /api/events endpoint every 3 seconds, which queries the recent_events Tinybird pipe for events from the last 5 minutes. Requests and downstream rows are validated, overlapping work is aborted, and events are deduplicated by stable event_id across polls.

// The polling hook
const { events, quarantine, status, lastSuccessAt, clear } =
  useEventStream(projectId, { includeQuarantine: true })

// Each event contains:
{
  event_id: "evt_01HXYZ...",
  event: "signup_completed",
  timestamp: "2026-02-05T12:34:56.789Z",
  distinct_id: "user_abc123",
  person_id: "person_123",
  session_id: "sess_xyz",
  properties: '{"plan": "pro", "source": "google"}',
  country: "US",
  city: "San Francisco",
  // returned when the deployed pipe includes them
  event_source: "browser",
  is_server_verified: false,
  conversion_authority: "browser_unverified"
}

Validation stages and ledger environment

For up to 100 event IDs per request, the debugger reads the ingest ledger that the Worker writes before each warehouse append. The inspector shows these stages:

1. Worker validation: passed when a ledger claim exists, because the Worker claims only accepted events.
2. Ledger claim: the ledger environment, batch, revision, and claim time.
3. Warehouse append: completed, pending, or ambiguous. An ambiguous append needs reconciliation before any retry.
4. Queryable: the analytics query returned the event ID. The analytics row does not record which ledger environment produced it.

The environment filter uses ledger evidence only. Ledger environments are the deployment environments (production, staging, test, local). An event without a claim shows No ledger evidence and is never assigned an environment. Ledger lookups are scoped to the current project, so another project's claims for the same event ID are not shown.

One event ID can have a claim in more than one ledger environment. When you select an environment, the stages, status dot and revision come from that environment's claim only. With All ledger environments, the inspector shows each environment's stages separately and a combined line with the most conservative append state: one ambiguous claim makes the event ambiguous even if another environment completed. The quarantine panel is project-wide; the environment filter does not apply to it.

Warehouse quarantine

Tinybird writes rows it cannot append to the automatic events_quarantine datasource. The recent_quarantine pipe returns this project's quarantined rows from the last 60 minutes, with Tinybird's error columns and messages. Deploy infra/tinybird/pipes/recent_quarantine.pipe with the dashboard_token READ scope before you rely on this panel. Until then the debugger shows Quarantine evidence unavailable with the reason. It never reports an undeployed or failed query as zero quarantined rows.

Next Steps

• Tracking events
• Autocapture events
• Governance and linting