Embedded mode

Run Trace inside your own backend on MongoDB or Postgres, with no separate server.

10 minutes

Run Trace inside the backend you already have, with no separate server or database. @trace-id/embed is the same identification engine as the standalone server, packaged as a library: you give it your database and mount one route.

Embedded (@trace-id/embed)Standalone server
RunsInside your app's processIts own service (Docker)
StorageYour MongoDB or Postgres, in trace_ collections or tablesIts own Postgres
Browser endpointYour API, for example https://api.yourapp.com/tracehttps://id.yourapp.com
Verify on your serverawait trace.verify(eventId), an in-process callGET /v1/events/:id with a secret key
Push eventsonEvent callbackSigned webhooks
Dashboard and MCPYour own toolsIncluded
Multiple projectsOne app per instanceMany projects

Choose embedded when you want Trace to be part of an app you already run. Choose the server when you want a self-contained service with its own dashboard, or several apps sharing one Trace.

Set up

TypeScript
import { createTrace } from '@trace-id/embed';
import { mongoStorage } from '@trace-id/embed/mongo';

export const trace = createTrace({ storage: mongoStorage(db), secret: process.env.TRACE_SECRET! });

secret must be at least 32 random characters and stay the same across restarts: it signs visitor tokens. Changing it makes returning visitors look new until their device traits match again.

Mount the browser route on your framework:

FrameworkMount
Express, Connectapp.use(toNodeHandler(trace)) (@trace-id/embed/node)
Fastify, NestJS on FastifyregisterFastify(fastifyInstance, trace) (@trace-id/embed/fastify)
NestJS on Expressapp.use(toNodeHandler(trace))
Next.js, Hono, Bun, Deno, Remix, SvelteKittoFetchHandler(trace) (@trace-id/embed/fetch)

Then point the browser SDK at it, endpoint: 'https://api.yourapp.com/trace', and verify on your server with trace.verify(eventId). See integration.md for where to identify and how to decide.

Important

Configure your framework's trusted proxy setting. Trace reads the client IP from it for VPN, datacenter and cross-browser signals; behind a load balancer without it, every visitor shares the balancer's address.

Storage

AdapterWhat it createsNotes
mongoStorage(db, { prefix, eventRetentionDays })Collections trace_visitors, trace_buckets, trace_profiles, trace_accounts, trace_events, with indexesNo transactions needed. Retention uses a TTL index.
postgresStorage(pool, { prefix, schema })Tables with the same namesCreated with CREATE TABLE IF NOT EXISTS on first use. One transaction per identification.
memoryStorage()NothingTests and development only.

Any other database can implement the TraceStorage interface. The storageContract test suite in the package source checks an adapter's behaviour.

Counters

Velocity and high-activity signals need counts per visitor, IP and account. The default counts in process, which is right for a single instance. With several instances pass redisCounters(redisClient): keys are prefixed trace:vel, so they can share your existing Redis. Pass counters: false to turn the two signals off.

Privacy

The same rules as the server apply: raw high-entropy readings never leave the browser, IPs are stored truncated by default (ipStorage), and deleteVisitor removes a visitor and everything stored about it. See privacy.md.

Edit this page on GitHub

This page is in the public repository: fix it and send a pull request.