analytics

Self-hosted product analytics: event tracking, user identification, funnel analysis, retention cohorts, real-time counters, and quota enforcement — all stored in your own Postgres. No third-party analytics vendor, no data leaving your instance. Ships a JavaScript browser SDK plus server-side SDKs for Go and TypeScript. Events are ingested asynchronously via a Redis-backed queue and materialized into query-ready aggregates on a configurable schedule.

Install

nself plugin install analytics
nself build
nself start

Configuration

Tracking events

# Track a server-side event via REST
curl -X POST https://api.yoursite.com/analytics/track \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "event": "subscription.created",
    "user_id": "user-uuid",
    "properties": {
      "plan": "pro",
      "amount_cents": 999
    }
  }'

# Identify a user (set profile properties)
curl -X POST https://api.yoursite.com/analytics/identify \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "user_id": "user-uuid",
    "traits": {
      "email": "alice@example.com",
      "name": "Alice"
    }
  }'

Browser SDK

# Install the JS SDK
pnpm add @nself/analytics-js

import { Analytics } from '@nself/analytics-js'

const analytics = new Analytics({
  writeKey: 'your-write-key',
  host: 'https://api.yoursite.com',
})

analytics.track('page.viewed', { path: window.location.pathname })
analytics.identify(userId, { email: user.email })

Quota enforcement

When ANALYTICS_QUOTA_ENABLED=true, each track call increments a Redis counter for the event name and user. Call /analytics/quota/check to test whether a user has exceeded a configured limit before performing an action. Quota definitions are stored in np_analytics_quotas and can be updated without a rebuild.

API reference

Database tables

• np_analytics_events — raw event log (pruned per retention policy)
• np_analytics_users — user trait store (identified profiles)
• np_analytics_aggregates — materialized event counts per time bucket
• np_analytics_funnels — saved funnel definitions
• np_analytics_quotas — quota rule definitions per event and user segment

Related

• entitlements: Feature gating — can read analytics quota state to gate access
• warehouse: Export analytics tables to BigQuery or Snowflake for BI tooling
• audit: Security-oriented event log — complements analytics for compliance use cases

Pro Plugin — ɳSelf+ | Port: 3206 | v1.1.1