https://github.com/user-attachments/assets/8a11590c-b2b8-49b6-9081-e1de44a17a95
Every signal about your product, in one place
TraceIQ captures what users do in your web, mobile and server apps, and what your app does back: events, page views, sessions, errors, logs and API calls. You explore it in one dashboard, act on it with flags and experiments, and keep the data on infrastructure you control.
Analytics
- Product analytics: events, insights, trends, funnels, retention, cohorts and user timelines with identity stitching.
- Web analytics: realtime visitors, referrers, UTM campaigns, goals, journeys and Core Web Vitals.
- Dashboards: saved views of any insight, with permission-scoped public links.
Session replay
- Session replay: consent-aware recordings with privacy controls, linked to the errors and events in each session.
Observability
- Error tracking: issues grouped by stack trace, with resolve, ignore and assign, and regressions flagged when a fixed issue comes back.
- Logs: structured logs from
traceiq.log() in the browser and Node SDKs, tied to sessions and requests.
- API performance and a requests explorer: latency, error rates and individual HTTP requests.
- Synthetic monitors: scripted checks that run on a schedule or in CI.
- Alerts: threshold monitors on any metric, delivered by email or webhook.
Ship and iterate
- Feature flags: percentage rollouts, targeting and remote config.
- Experiments and surveys: test changes and ask users directly.
Data and integrations
AI and developer tools
- Ask TraceIQ: ask questions about your data in plain language.
- MCP server: connect Claude, Cursor or any MCP client to your analytics.
- CLI: set up the SDK, switch projects, pull env vars and tail logs from your terminal.
- Add the MCP server to your client with
npx -y traceiq-mcp-server and a personal access token from Settings → Personal access tokens. Setup for Claude Desktop and Cursor: MCP docs.
- Agents can drive the CLI non-interactively:
TRACEIQ_TOKEN=tiq_pat_... npx traceiq-cli logs --level error --since 1h --json prints one JSON object per line. See the CLI README.
- To instrument an app, run
npx traceiq-cli --project-id <id> --write-key <key> --skip-verify. It detects Next.js, Vite + React and Node projects.
Table of contents
Getting started
TraceIQ Cloud
The hosted version runs at traceiq.run. Accounts are opened in batches: request access and you'll get an invite.
Self-hosting
Run a complete private instance on your own machine with one command. It needs Docker with Compose:
git clone https://github.com/enigma-137/trace-iq.git && cd trace-iq
docker compose -f compose.local.yml up -d --build
Open http://localhost:3000. PostgreSQL, Redis, migrations, the API and the dashboard start automatically. No account is needed: the stack creates a local workspace and project.
Project ID: proj_local
Write key: trq_local_development_only
API URL: http://localhost:4000
Local mode is for one person on their own machine; both ports bind to 127.0.0.1. For a shared server with accounts, teams, invitations and 2FA, follow the deployment guide: Docker Compose (API, PostgreSQL 18, Redis 7) behind Caddy, with the dashboard on Vercel or any Node.js host.
TraceIQ is under active development. Back up your database before upgrading a production instance.
Setting up TraceIQ
The fastest way is the setup wizard. Run it in your app's folder:
npx traceiq-cli
It detects your framework, installs the SDK, writes your project ID and write key to the env file, and waits until your first event arrives. Or add an SDK yourself:
npm install traceiq-sdk-js
import { traceiq } from 'traceiq-sdk-js';
traceiq.initialize({
projectId: 'YOUR_PROJECT_ID',
writeKey: 'YOUR_WRITE_KEY',
endpoint: 'https://api.traceiq.run',
autoTrackPageViews: true
});
traceiq.track('signup_completed', { plan: 'starter' });
SDKs
Anything else can send events to the HTTP API.
From the terminal
The same CLI manages your projects once you're set up:
npx traceiq-cli login # paste a personal access token
npx traceiq-cli projects use # pick a project
npx traceiq-cli env pull # write TRACEIQ_* vars to .env.local
npx traceiq-cli logs --follow # stream logs
npx traceiq-cli errors # list error issues
See the CLI README for every command.
How it works
SDKs, CLI, MCP clients
│
▼
NestJS API (apps/api) ── Redis
│
▼
PostgreSQL 18
▲
│
Next.js dashboard (apps/dashboard)
More detail: Architecture · Event schema · Privacy and data collection · Deployment
apps/api/ NestJS API, migrations and tests
apps/dashboard/ Next.js dashboard and public docs
packages/ JS, Node, React Native and Flutter SDKs, CLI, MCP server, shared packages
sdks/ Python, Rust, Swift and Kotlin SDKs
src/ and tests/ PHP SDK
docs/ Architecture, deployment and protocol docs
Developing TraceIQ
You need Node.js 22, npm 10+ and Docker. Install dependencies, start the database services, and run the API and dashboard with hot reload:
npm ci --legacy-peer-deps
docker compose -f compose.local.yml up -d postgres redis
Set AUTH_MODE=local for the API and NEXT_PUBLIC_AUTH_MODE=local for the dashboard, then run npm run dev. Before opening a pull request:
npm run typecheck
npm test --workspace=@traceiq/api
npm test --workspace=@traceiq/dashboard
npm run build
Contributing
We'd love your help:
License
TraceIQ is open source under the MIT License. That covers the whole repository; there is no separate enterprise-licensed code.
