Pulse (Usage Telemetry)

Pulse is the usage telemetry service for the Shift Platform. It tracks events, supports batch ingestion, and generates reports on event activity.

What It Does

• Event Tracking — Track individual events with properties, user IDs, and session IDs.
• Batch Ingestion — Ingest multiple events in a single request for high-throughput scenarios.
• Reporting — Generate reports such as top events to understand usage patterns.

Key Concepts

Concept	Description
Event	A tracked occurrence with a name, optional properties, and metadata (user, session, timestamp).
Batch	A collection of events submitted in a single API call for efficient ingestion.
Report	An aggregated view of event data (e.g., top events by count).

Configuration

Setting	Value
Storage Directory	.pulse/
API Dev Port	4003
Web Dev Port	4103
Gateway Prefix	/api/v1/pulse/*

Getting Started

Track your first event:

shift-cli pulse events track

Or via the API:

curl -X POST http://localhost:3000/api/v1/pulse/events \
  -H "Content-Type: application/json" \
  -d '{
    "name": "page.viewed",
    "properties": {"page": "/dashboard"},
    "userId": "user-abc"
  }'

Then view events and reports:

shift-cli pulse events list
shift-cli pulse reports top