TraceIQ

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

• Webhooks and data export (CSV, JSON, API).
• HTTP ingestion API for any language or platform.

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
  • Self-hosting
• Setting up TraceIQ
  • SDKs
  • From the terminal
• How it works
• Developing TraceIQ
• Contributing
• License

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

Frontend	Mobile	Backend
JavaScript · traceiq-sdk-js	React Native / Expo · traceiq-react-native	Node.js
Next.js	Flutter	Python · traceiq-py
React (Vite)	Swift (iOS)	Rust · traceiq
	Kotlin (Android)	PHP

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:

• Open a pull request. Read CONTRIBUTING.md first; it covers setup, tests and the browser smoke tests.
• Report a bug or request a feature.
• Found a security issue? Please report it privately as described in SECURITY.md, not in a public issue.

License

TraceIQ is open source under the MIT License. That covers the whole repository; there is no separate enterprise-licensed code.