@tracelog/event-contract

The TraceLog event envelope: one definition of the wire format, its limits and its schemas. The capture runtime is built from it and TraceLog's ingestion validates every batch against it, so a field means the same thing on both sides of the wire. Two definitions of one wire format drift, and drift at the wire is silent data loss.

This package is published so that the SDK's source can be read, which wordpress.org requires of the plugin bundle, and so that anything sending TraceLog events from a runtime of its own can be checked against the same schemas rather than a copy of them. Sites installing TraceLog do not need it: @tracelog/capture-web carries the limits it uses inside its bundle.

https://tracelog.io

Install

npm install --save-exact @tracelog/[email protected]

What it holds

• EVENT_ENVELOPE_VERSION — the v a batch carries. What a runtime writes is this constant; what ingestion accepts is a set, which only ever grows, so a page pinned to an old runtime keeps being accepted.
• The limits — batch events, batch bytes, context bytes, error-message bytes, the tolerance for a clock ahead of the server, and when an event is late rather than wrong.
• The schemas — zod, for the envelope and every event in it, plus validateEventBatch, which accepts a batch whole — flagging each event that arrived late — or refuses it whole, with one classification the sender can read.
• The tag sighting — tagSightingReportSchema, the report a conversion's context carries under TAG_SIGHTINGS_CONTEXT_KEY — the tags sighted, whether the report is complete, and from 1.2.0 the kinds it saw requested and could not read — and the patterns its ids and events are held to, as strings the runtime inlines. The envelope does not validate it; the platform reads it, and a value that fails it is no report.
• The items — itemSchema and itemsSchema, scheduledForSchema and their limits. Where its event takes it, a malformed one is read as absent and the event stands.
• The opening — opening: "page" on a session_start the runtime sent because a page loaded; absent, the session opened on an event.

Licence

MIT. See LICENSE.