Pulse Analytics is a self-hosted, cloud-native analytics service for teams that want the breadth of a modern product analytics stack without locking all product data into one vendor. It combines web analytics, product analytics, event collection, session intelligence, feature workflows, privacy controls, BI, and data routing behind one Rust service and one lightweight SDK.
The product bet is simple:
- Install in minutes.
- Track without slowing down the website.
- Keep data portable.
- Let teams bring their own database or warehouse.
- Make integration language-neutral: every app can call plain HTTP.
Pulse includes the core pieces usually split across several products:
- Web analytics: pageviews, referrers, devices, geo, realtime visitors, UTM and campaign reporting.
- Product analytics: custom events, funnels, goals, retention, cohorts, paths, activation reports, lifecycle reports, product impact analysis, dashboards, saved reports, and query explorer history.
- Identity and account analytics: user profiles, aliases, identity graph, account profiles, account members, SCIM users, and SCIM groups.
- Session intelligence: visitor timelines, session detail, session replay, scroll depth, outlinks, search queries, click heatmaps, visual event labels, and friction signals.
- Experimentation and activation: feature flags, remote config, A/B tests, surveys, NPS, sentiment, and in-app guides.
- Reliability analytics: JavaScript errors, releases, source maps, logs, alerts, and webhook notifications.
- AI and LLM analytics: natural-language analytics query helper, insights, LLM traces, generations, evaluations, token usage, latency, and cost stats.
- CDP-style data movement: event sources, source ingestions, destinations, retryable delivery outbox, signed webhooks, and destination health.
- BI layer: semantic metrics, row policies, SQL editor, visual queries, drill-through, CSV uploads, database connections, saved SQL, embeds, and query run history.
- Privacy and governance: data retention, IP anonymization, DNT/GPC handling, consent modes, bot filtering, DSAR export/delete, audit logs, tracking plans, event schemas, data dictionary, and instrumentation health.
Most analytics tools optimize for one of these modes:
- Product analytics, like funnels and retention.
- Website analytics, like pageviews and attribution.
- Session replay and heatmaps.
- Feature flags and experiments.
- CDP event routing.
- BI dashboards.
Pulse is designed to make those workflows live together while staying developer-friendly and self-hostable. The newest core differentiators are:
- Low-overhead ingestion: browser SDK batching is on by default and flushes
with
sendBeaconwhere available. - Language-neutral batch API: any stack can POST events to
/api/batch. - Bring-your-own-database BI: query Pulse data, Postgres databases,
ClickHouse, or any external warehouse exposed through the
http_jsonadapter. - Data ownership: Postgres stores Pulse control-plane and analytics data by default; Redis handles buffering, API-key cache, realtime state, and rate limiting.
- Single service deployment: Rust/Axum server, embedded docs, embedded tracking script, migrations on startup, and Docker support.
.
|-- crates/
| |-- pulse-server/ # Rust Axum server, routes, services, templates
| `-- pulse-common/ # Shared request/response types
|-- sdk/ # TypeScript SDK and browser auto-tracking script
|-- migrations/ # SQLx migrations
|-- docs/ # Implementation notes and product roadmap
|-- scripts/ # VPS setup and project onboarding helpers
|-- Dockerfile
|-- docker-compose.yml
|-- docker-compose.coolify.yml
|-- Makefile
`-- README.md
flowchart LR
A["Website / App"] --> B["Pulse SDK or HTTP API"]
B --> C["Axum ingestion routes"]
C --> D["Redis buffers"]
D --> E["Background flush workers"]
E --> F["PostgreSQL analytics tables"]
F --> G["Query API and Dashboard"]
F --> H["BI layer"]
H --> I["Postgres / ClickHouse / HTTP JSON adapters"]
C --> J["Destination outbox"]
J --> K["Webhooks and external systems"]
Key runtime components:
- Rust server: Axum routes, SQLx, Redis, background tasks, Askama templates.
- PostgreSQL: projects, API keys, sessions, events, pageviews, rollups, BI, governance, privacy, identity, replay, and feature data.
- Redis: ingestion buffers, realtime visitor sorted sets, API-key cache, session resolution, and rate limiting.
- TypeScript SDK: browser client, server client, React, Vue, Next.js, and React Native helpers.
- Static script:
/api/script.jsserves the minified browser tracker fromcrates/pulse-server/static/pulse.min.js.
The easiest local setup starts Pulse, Postgres, and Redis together.
make docker-upThen open:
- Home:
http://localhost:8090/ - Health:
http://localhost:8090/health - API docs:
http://localhost:8090/api/docs - Dashboard:
http://localhost:8090/dashboard
The local compose file exposes:
- Pulse:
localhost:8090 - Postgres:
localhost:5434 - Redis:
localhost:6381
Stop everything:
make docker-downPrerequisites:
- Rust toolchain
- Node.js and npm
- PostgreSQL
- Redis
Build everything:
make buildRun the server against local services:
export PULSE_PORT=8090
export ENVIRONMENT=development
export DATABASE_URL='postgres://pulse:pulse@localhost:5434/pulse_analytics?sslmode=disable'
export REDIS_URL='redis://localhost:6381/0'
export REDIS_KEY_PREFIX='pulse_analytics:'
export PULSE_ADMIN_TOKEN='dev-admin-token'
export ALLOWED_ORIGINS='*'
export RUST_LOG=debug
cargo run -p pulse-serverThe server runs SQL migrations automatically on startup.
make build # Build SDK, copy browser script, build Rust release binary
make build-sdk # Build TypeScript SDK and update static pulse.min.js
make build-server # Build Rust server in release mode
make dev # Run pulse-server locally
make dev-watch # Run with cargo-watch
make check # cargo check
make docker # Build Docker image
make docker-up # Start Docker Compose stack
make docker-down # Stop Docker Compose stack
make clean # Remove Rust and SDK build artifacts
make publish-sdk # Publish npm SDK| Variable | Required | Default | Purpose |
|---|---|---|---|
PULSE_PORT |
No | 8090 |
HTTP port for the server. |
ENVIRONMENT |
No | development |
Environment label; use production for production. |
DATABASE_URL |
Yes | none | PostgreSQL connection string. |
REDIS_URL |
Yes | none | Redis connection string. |
REDIS_KEY_PREFIX |
No | pulse_analytics: |
Prefix for Redis keys. |
PULSE_ADMIN_TOKEN |
Yes | none | Bearer token for admin routes. |
PULSE_COOKIE_SECRET |
Production recommended | generated in memory | Cookie signing secret for dashboard sessions. |
ALLOWED_ORIGINS |
No | empty | Comma-separated CORS allow-list. Use * only for local/dev. |
GEOIP_DB_PATH |
No | none | Optional MaxMind database path. |
BUFFER_FLUSH_INTERVAL_SECS |
No | 5 |
Redis buffer flush interval. |
BUFFER_BATCH_SIZE |
No | 500 |
Max items flushed from each buffer per cycle. |
RATE_LIMIT_PER_SECOND |
No | 100 |
Per-key/IP ingestion rate limit. |
DATA_RETENTION_DAYS |
No | 365 |
Retention task cutoff. |
UMAMI_URL |
No | none | Optional Umami proxy URL. |
UMAMI_USER |
No | none | Optional Umami user. |
UMAMI_PASS |
No | none | Optional Umami password. |
EMAIL_REPORT_WEBHOOK_URL |
No | none | Optional email report delivery webhook. |
RUST_LOG |
No | info |
Rust tracing filter. |
Admin routes use:
Authorization: Bearer <PULSE_ADMIN_TOKEN>
Create a project:
curl -sS -X POST http://localhost:8090/api/admin/projects \
-H 'Authorization: Bearer dev-admin-token' \
-H 'Content-Type: application/json' \
-d '{
"name": "Demo App",
"domain": "localhost",
"settings": {}
}'Create an ingest key:
curl -sS -X POST http://localhost:8090/api/admin/projects/<project_id>/keys \
-H 'Authorization: Bearer dev-admin-token' \
-H 'Content-Type: application/json' \
-d '{
"name": "web-ingest",
"scopes": ["ingest"]
}'Create a query key:
curl -sS -X POST http://localhost:8090/api/admin/projects/<project_id>/keys \
-H 'Authorization: Bearer dev-admin-token' \
-H 'Content-Type: application/json' \
-d '{
"name": "dashboard-query",
"scopes": ["query"]
}'API keys are returned once. Store them immediately.
All ingestion routes require an API key with the ingest scope. Send it either
as X-Pulse-Key or as ?key=... for beacon-friendly browser requests.
curl -sS -X POST http://localhost:8090/api/collect \
-H 'Content-Type: application/json' \
-H 'X-Pulse-Key: <ingest_key>' \
-d '{
"type": "event",
"visitor_id": "visitor_123",
"payload": {
"name": "signup_clicked",
"path": "/pricing",
"data": { "plan": "pro" }
},
"consent_mode": "analytics",
"consent_granted": true
}'Use /api/batch to reduce network overhead or send backend/worker events in
bulk. A batch accepts up to 100 envelopes.
curl -sS -X POST http://localhost:8090/api/batch \
-H 'Content-Type: application/json' \
-H 'X-Pulse-Key: <ingest_key>' \
-d '{
"events": [
{
"type": "pageview",
"visitor_id": "visitor_123",
"payload": {
"path": "/",
"title": "Home",
"referrer": ""
}
},
{
"type": "event",
"visitor_id": "visitor_123",
"payload": {
"name": "cta_clicked",
"path": "/",
"data": { "variant": "hero" }
}
}
]
}'Supported event types include:
pagevieweventidentifyweb_vitalscroll_depthsearch_queryoutlinkjs_errorlogclick_eventsurvey_responsesession_replay
The no-build integration is one script tag:
<script
async
src="https://your-pulse-host.com/api/script.js"
data-key="pa_live_xxx"
data-api="https://your-pulse-host.com"
data-batch="true"
data-batch-size="10"
data-batch-interval="2000"
data-vitals="true"
data-errors="true"
data-outlinks="true"
></script>Important attributes:
| Attribute | Default | Purpose |
|---|---|---|
data-key |
required | Ingest API key. |
data-api |
current origin fallback | Pulse API base URL. |
data-batch |
true |
Enable browser event queueing. |
data-batch-size |
10 |
Flush once this many events are queued. |
data-batch-interval |
2000 |
Flush interval in milliseconds. |
data-dnt |
true |
Respect browser Do Not Track. |
data-consent-mode |
analytics |
Consent mode sent to server. |
data-consent-granted |
true |
Whether tracking consent is granted. |
data-utm |
true |
Persist and attach UTM parameters. |
data-scroll |
false |
Track scroll depth. |
data-vitals |
false |
Track Core Web Vitals. |
data-outlinks |
false |
Track downloads and external links. |
data-errors |
false |
Track JS errors and unhandled rejections. |
data-clicks |
false |
Track click heatmap points. |
data-search |
false |
Track search query param. |
data-replay |
false |
Track sampled session replay events. |
Manual browser calls:
window.pulse("event", "signup_clicked", { plan: "pro" });
window.pulse("identify", "user_123", { email: "user@example.com" });
window.pulse("search", "analytics tools", 42);
window.pulse("log", "error", "Checkout failed", { code: "card_declined" });
window.pulse("consent", true, "analytics");The SDK package is @ayushojha/pulse-analytics.
cd sdk
npm ci
npm run buildBrowser client:
import { createPulse } from "@ayushojha/pulse-analytics";
const pulse = createPulse({
apiKey: "pa_live_xxx",
apiUrl: "https://your-pulse-host.com",
batch: true,
batchSize: 10,
batchFlushIntervalMs: 2000,
trackWebVitals: true,
trackErrors: true,
});
pulse.event("signup_clicked", { plan: "pro" });
pulse.identify("user_123", { email: "user@example.com" });
await pulse.flush();Server client:
import { PulseServerClient } from "@ayushojha/pulse-analytics/server";
const pulse = new PulseServerClient({
apiKey: "pa_live_xxx",
apiUrl: "https://your-pulse-host.com",
});
await pulse.trackEvent({
visitorId: "visitor_123",
eventName: "purchase",
data: { plan: "pro" },
revenueAmount: 49,
revenueCurrency: "USD",
});
await pulse.collectBatch([
{
type: "event",
visitorId: "visitor_123",
payload: {
name: "invoice_paid",
data: { invoice_id: "inv_123" },
},
},
]);Framework entrypoints:
@ayushojha/pulse-analytics@ayushojha/pulse-analytics/server@ayushojha/pulse-analytics/react@ayushojha/pulse-analytics/vue@ayushojha/pulse-analytics/next@ayushojha/pulse-analytics/react-native
Query routes require a key with the query scope.
curl -sS 'http://localhost:8090/api/v1/stats?start_at=2026-01-01T00:00:00Z&end_at=2026-01-31T23:59:59Z' \
-H 'X-Pulse-Key: <query_key>'Core query endpoints:
GET /api/v1/statsGET /api/v1/stats/timeseriesGET /api/v1/pagesGET /api/v1/referrersGET /api/v1/eventsGET /api/v1/devicesGET /api/v1/geoGET /api/v1/realtime
Feature endpoint groups include:
/api/v1/funnels/api/v1/goals/api/v1/retention/api/v1/cohorts/api/v1/paths/api/v1/campaigns/api/v1/marketing/*/api/v1/identity/*/api/v1/scim/*/api/v1/segments/api/v1/governance/*/api/v1/privacy/*/api/v1/feature-flags/api/v1/experiments/api/v1/session-replay/api/v1/heatmaps/api/v1/surveys/api/v1/guides/api/v1/errors/api/v1/logs/api/v1/alerts/api/v1/sources/api/v1/destinations/api/v1/ai/*/api/v1/bi/*
For full request and response examples, run the server and open
/api/docs.
Pulse can query its own analytics tables and external BI connections.
Supported external connection types:
| Type | Connection string | Notes |
|---|---|---|
postgres |
postgres://... or postgresql://... |
Runs in a read-only transaction and applies allowed_schemas as the search path. |
clickhouse |
https://user:pass@clickhouse.example.com:8443/?database=analytics |
Uses ClickHouse HTTP API, read-only mode, JSONEachRow, and exactly one allowed database. |
http_json |
https://adapter.example.com/query |
Universal adapter for any database/warehouse. Adapter receives SQL, limit, and allowed_schemas. |
Create a BI connection:
curl -sS -X POST http://localhost:8090/api/v1/bi/connections \
-H 'X-Pulse-Key: <query_or_admin_key>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Warehouse",
"database_type": "http_json",
"connection_string": "https://adapter.example.com/query",
"allowed_schemas": ["analytics"],
"is_active": true
}'Run external SQL:
curl -sS -X POST http://localhost:8090/api/v1/bi/connections/<connection_id>/query \
-H 'X-Pulse-Key: <query_or_admin_key>' \
-H 'Content-Type: application/json' \
-d '{
"sql_text": "SELECT event_name, count(*) AS events FROM events GROUP BY event_name",
"limit": 100
}'HTTP adapter contract:
{
"sql": "SELECT ...",
"limit": 100,
"allowed_schemas": ["analytics"],
"enforce_allowed_schemas": true
}The adapter may return either:
[{ "column": "value" }]or:
{ "rows": [{ "column": "value" }] }or:
{ "data": [{ "column": "value" }] }Security behavior for HTTP adapters:
- Localhost, private, link-local, multicast, unspecified, and reserved IP ranges are blocked.
- Redirects are disabled.
- Userinfo passwords and common secret query parameters are redacted in API responses.
- ClickHouse connections must use exactly one allowed database.
http_jsonadapters must enforceallowed_schemaswith their own database credentials and query sandboxing.
Pulse projects use module flags in project settings. core is always enabled.
Default enabled modules include:
coreidentitysegmentsdashboardsgovernanceutmgoalsfunnelsretentionexportsintegrationssourcesdestinationsbialertsfeature_flagsrevenueerror_trackinglogs
Available modules also include:
cohortspathswebvitalsscrollsearchoutlinkssharingemail_reportsab_testingsession_replayheatmapsai_queriespredictionssurveys
API keys can also be restricted to specific modules with allowed_modules.
Pulse has built-in controls for:
- IP anonymization.
- DNT and Global Privacy Control handling.
- Consent-required ingestion.
- Allowed consent modes.
- Bot filtering and blocked user agents.
- Data retention windows.
- DSAR export and delete.
- Audit logs.
- Tracking plans.
- Event schema validation.
- Data dictionary entries.
- Quality violation reports.
- Instrumentation health.
The ingestion route accepts skipped events as successful no-ops when privacy rules reject tracking, so applications do not break when consent is denied.
The server starts these background tasks:
- Redis buffer flush worker.
- Daily rollup worker.
- Partition management worker.
- Retention cleanup worker.
- Webhook alert worker.
- Destination delivery worker.
- Email report scheduler.
The first migrations create:
projectsapi_keyssessionspageviewsevents- daily rollups for stats, pages, referrers, events, geo, and devices
Later migrations add identity, modules, webhooks, governance, privacy, feature flags, errors, AI/LLM analytics, BI, embeds, marketing imports, SCIM, sources, destinations, surveys, guides, and more.
pageviews and events are partitioned by time, and the partition worker keeps
future partitions ready.
docker build -t pulse-analytics .
docker run --rm -p 8090:8090 \
-e DATABASE_URL='postgres://...' \
-e REDIS_URL='redis://...' \
-e PULSE_ADMIN_TOKEN='change-me' \
pulse-analyticsUse docker-compose.coolify.yml as the deployment shape for Coolify-style
stacks. Override secrets through environment variables rather than committing
production credentials.
- Set a strong
PULSE_ADMIN_TOKEN. - Set a stable
PULSE_COOKIE_SECRET. - Restrict
ALLOWED_ORIGINS. - Use managed Postgres backups.
- Use Redis persistence or managed Redis where appropriate.
- Put Pulse behind TLS.
- Keep external BI adapter URLs on public, trusted hosts.
- Use least-privilege database credentials for every external BI connection.
- Restrict API key scopes and
allowed_modules. - Monitor
/health. - Review retention and privacy settings before collecting real user data.
Run all Rust tests:
cargo test --workspace --no-fail-fastRun type/build verification for the SDK:
cd sdk
npm run buildRun a quick compile check:
cargo check --workspaceAfter SDK changes, rebuild and copy the browser script:
make build-sdk- Live API docs:
/api/docs - Product positioning and roadmap:
docs/competitive-positioning-and-roadmap.md - Phase implementation notes:
docs/phase-*-implementation.md
Near-term priorities:
- Publish OpenAPI and copy-paste snippets for JavaScript, Python, Go, Ruby, PHP, Java, cURL, Cloudflare Workers, and serverless functions.
- Add official
http_jsonadapter examples for MySQL, BigQuery, Snowflake, DuckDB, SQLite, and warehouse-first teams. - Add benchmark tests for SDK payload size, request count, ingestion latency, and dashboard query latency.
- Add a ClickHouse storage backend for Pulse hot event tables while keeping Postgres as the control plane.
- Expand destinations beyond webhooks into warehouse and database sinks.
- Add setup health checks for tracking, batching, privacy, replay, vitals, flags, and external BI.
MIT.