Event tracking, counters, funnels, and quota management analytics engine for nself. Track user behavior, measure conversion rates, enforce rate limits, and build real-time dashboards.

nself plugin run analytics init
nself plugin run analytics server

Counters auto-increment across four time periods simultaneously:

When an event is tracked via POST /v1/events, a matching counter is automatically incremented for the event name. Counters use upsert logic with ON CONFLICT ... DO UPDATE SET value = value + increment.

The rollup operation aggregates hourly counters into daily and daily into monthly using SUM() with GROUP BY DATE_TRUNC(). Trigger manually via POST /v1/counters/rollup or the rollup CLI command.

Funnels define a sequence of steps (events) that users should complete in order. The analysis engine:

1. Counts unique user_id values for the first step event
2. For each subsequent step, joins on user_id where the next event occurred within window_hours of the previous event
3. Returns per-step user counts, conversion rates, and drop-off rates

{
  "name": "Sign Up",
  "event_name": "user.signup",
  "filters": { "plan": "pro" }
}

{
  "funnel_id": "...",
  "funnel_name": "Onboarding",
  "steps": [
    { "step_number": 1, "step_name": "Visit", "event_name": "page.view", "users": 1000, "conversion_rate": 100, "drop_off_rate": 0 },
    { "step_number": 2, "step_name": "Sign Up", "event_name": "user.signup", "users": 400, "conversion_rate": 40, "drop_off_rate": 60 },
    { "step_number": 3, "step_name": "Purchase", "event_name": "order.placed", "users": 80, "conversion_rate": 20, "drop_off_rate": 80 }
  ],
  "total_entered": 1000,
  "total_completed": 80,
  "overall_conversion_rate": 8
}

Quotas enforce limits on counter values. When a quota check finds the counter would exceed max_value, the system records a violation and returns allowed: false.

{
  "allowed": false,
  "quota_name": "Daily API Calls",
  "current_value": 1001,
  "max_value": 1000,
  "remaining": -1,
  "action": "block"
}

Unique constraint: (source_account_id, counter_name, dimension, period, period_start)

Standard webhook event tracking table with id, source_account_id, event_type, payload (JSONB), processed, processed_at, error, created_at.

The GET /v1/dashboard endpoint returns a comprehensive view:

Events not appearing -- Verify event_name is provided in the request body. Check that the API key matches if ANALYTICS_API_KEY is set.

Counter values seem wrong -- Counters auto-increment across all four periods. Use the period query parameter to check specific time buckets. Run rollup to re-aggregate.

Funnel shows 0 users -- Funnel analysis requires events with non-null user_id. Verify events exist for all step event names.

Quota not enforcing -- Confirm the quota is enabled: true and the counter_name matches an existing counter. Quotas match by scope_id first, then fall back to scope_id IS NULL.

Batch rejected -- Ensure the events array does not exceed ANALYTICS_BATCH_SIZE (default: 100).