@sophonz/user-event

한국어

User event lifecycle tracking for custom user journeys in OpenTelemetry.

Tracks named user activities (e.g., "checkout flow", "form submission") as OTel spans with automatic lifecycle management, localStorage persistence, and context binding.

Part of the Sophonz OpenTelemetry suite.

Install

bun add @sophonz/user-event
# or
pnpm add @sophonz/user-event
# or
npm install @sophonz/user-event

Usage

import { UserEvent } from '@sophonz/user-event';

// Create instance
const userEvent = new UserEvent(contextManager, tracer);

// Start tracking an event
const eventId = userEvent.start('checkout-flow', {
  cartValue: 99.99
});

// ... user performs actions ...

// End the event
userEvent.end(eventId, {
  status: 'completed'
});

// Or cancel if not completed
userEvent.cancel(eventId);

// Get currently active event
const active = userEvent.getActive();

Event Lifecycle

Events are tracked as OTel spans with automatic attributes:

• app.span.type: 'user_event'
• user_event.duration_ms - Total milliseconds
• user_event.end_time - Unix timestamp at end
• user_event.cancelled - Set on a cancelled event
• Custom attributes passed at start/end

Persistence

Events are persisted to localStorage and automatically restored on page reload, enabling cross-navigation event tracking within a single session.

API

UserEvent

Constructor

constructor(contextManager: SophonzContextManager, tracer?: Tracer)

Methods

• start(name?, attributes?) - Begin event, returns event ID
• end(id, attributes?) - Complete event with optional final attributes
• cancel(id) - Cancel event without recording
• getActive() - Get current active event
• hasActiveEvents() - Check if any events are in progress
• getActiveEventIds() - Get all active event IDs
• getStoredEvents() - Get persisted events from localStorage
• hasStoredEvent(id) - Check if event is persisted
• cleanup() - Clear all localStorage records (call on page unload)

Peer Dependencies

• @opentelemetry/api@^1.9.1

License

See LICENSE in this package.

Part of sophonz-js.