Eventvisor concepts - Eventvisor

Eventvisor is a Git based control plane for analytics events and logs. Teams review tracking contracts as code, then applications enforce those contracts locally through generated datafiles.

The two sides of Eventvisor#

An Eventvisor integration has two independent sides:

The project contains authored definitions, tests, and Targets. The CLI validates these files and builds static JSON datafiles.
The application loads a datafile through an SDK. The SDK validates, transforms, filters, samples, and routes events without contacting Eventvisor.

This separation lets governance changes ship independently from application deployments. Eventvisor does not require a hosted control service and does not own your event destination.

Project definitions#

The main authored entities are:

Entity	Purpose
Attributes	Context such as a user, device, application, or consent state
Events	Analytics and log payload contracts, with runtime processing rules
Schemas	Reusable JSON Schema structures shared by events and attributes
Destinations	Named routes that connect governed events to transport modules
Effects	Stateful reactions to tracked events and attribute changes
Targets	Named, dependency-aware selections that become datafiles
Tests	Declarative expectations for the same pipeline used by SDKs

Sources, conditions, transforms, and sampling form the reusable runtime language across these entities.

Targets and datafiles#

A Target describes what one application or service needs. Building the project produces one datafile for every Target:

targets/web.yml       -> datafiles/eventvisor-web.json
targets/backend.yml   -> datafiles/eventvisor-backend.json

Tags are selection metadata. They can help a Target select related definitions, but tags do not generate files by themselves.

Eventvisor follows references and keeps required dependencies. For example, an included event retains its required attributes, destination overrides, quarantine destination, triggered effects, and the definitions those effects use.

Runtime pipeline#

When an application calls track(), the SDK processes the event locally:

lookup -> required attributes -> validation -> conditions -> sampling
       -> event transforms -> effects -> destination rules and transforms
       -> transport modules

The SDK owns governance. Transport modules own delivery behaviour such as immediate sending, batching, retries, browser lifecycle handling, and flushing. Read the event pipeline for the exact processing and readiness contract.

Modules#

Modules add capabilities to an SDK instance without adding vendor-specific behaviour to the core runtime. A module can provide one or more of these capabilities:

transport events to a destination
resolve lookup values
run effect handlers
persist attributes or effect state
flush queued work and release resources

Applications choose which modules they trust and install. A datafile can refer to a module by name, but it cannot install code into an application.

Sets and promotions#

Sets contain several isolated Eventvisor projects in one repository. They are useful when development, staging, and production need genuinely different definitions, tests, state, and datafiles.

Promotions preview and merge definitions from one Set to another. Targets still exist inside each Set. The two concepts solve different problems:

Sets are independent authoring and release lanes.
Targets are application-specific output slices within one lane.

Git based workflow#

A typical change follows this path:

edit definitions -> lint and test -> pull request review -> build datafiles
                 -> deploy to your CDN -> applications refresh datafiles

The Catalog gives engineering, product, analytics, and governance teams a readable view of definitions, tests, dependencies, Targets, and Git history.

Continue with the quick start to build and consume a small project.