apitrail

Self-hosted request logging for Next.js. Your data. Your database. Zero SaaS.

Drop-in observability for Next.js App Router — every request, every body, every child span — persisted to your own Postgres. The open-source alternative to Sentry & Datadog for API observability.

Quick start · Integrating · Studio setup · Security · Agents

---

⚡ Integrate in 30 seconds

pnpm dlx @apitrail/cli install   # installs + wires everything for Next.js
pnpm dlx @apitrail/studio        # opens the dashboard at http://localhost:4545

That's it — hit any route in your app and watch requests land live.

_{npm / yarn / bun are detected automatically. Want to see every option or set it up by hand? → Quick start.}

---

✨ Why apitrail?

pnpm dlx @apitrail/cli install

^{↑ One line. Detects your stack. Installs deps. Writes the instrumentation. Creates the table. Done.}

You get Sentry-quality request traces without sending data to a SaaS: every method, path, status, duration, full request/response bodies, headers, errors, and the complete waterfall of child spans — all persisted to a single table in a Postgres you already own.

	apitrail	Sentry / Datadog	OTEL stack (SigNoz, Jaeger…)
Where your data lives	🏠 Your Postgres	☁️ Their cloud	⚙️ Collector + ClickHouse you run
Setup time	⚡ 60 seconds	~30 min	~half a day
Captures request/response bodies	✅ with PII masking	⚠️ paid tier + careful config	❌ not by default
Child-span waterfall	✅	✅	✅
Cost @ 10M requests/mo	💰 your DB bill	💸 $$$	💰 your compute bill
Ops overhead	1 table	0 (SaaS)	a lot
Open source	✅ MIT	—	✅

---

🚀 Quick start

The one-liner

pnpm dlx @apitrail/cli install

The wizard will:

1. 🔎 Detect your package manager (pnpm / npm / yarn / bun) and Next.js version
2. 📄 Read DATABASE_URL from .env.local or prompt
3. 📦 Install @apitrail/core + @apitrail/postgres + pg
4. ✍️ Write an edge-safe instrumentation.ts (backing up any existing one)
5. 🔐 Append DATABASE_URL to .env.local if missing
6. 🗄️ Create the apitrail_spans table in your database
7. (optional) 🖼️ Scaffold app/apitrail/[[...path]]/page.tsx with the embedded dashboard

# non-interactive, CI-safe:
DATABASE_URL="postgres://…" pnpm dlx @apitrail/cli install --yes --with-dashboard

Or manually

Click to expand

pnpm add @apitrail/core@alpha @apitrail/postgres@alpha
pnpm dlx @apitrail/cli@alpha init     # create the table

// instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME !== 'nodejs') return

  const { defineConfig, register: apitrailRegister } = await import('@apitrail/core')
  const { postgresAdapter } = await import('@apitrail/postgres')

  await apitrailRegister(
    defineConfig({
      adapter: postgresAdapter({ connectionString: process.env.DATABASE_URL }),
    }),
  )
}

Full config reference in INTEGRATING.md.

---

👀 See your data

_{@apitrail/studio — requests list + trace detail with waterfall and redacted bodies.}

Option A — standalone studio 🔥 recommended

pnpm dlx @apitrail/studio

Opens http://localhost:4545 with a beautiful dark dashboard — Prisma Studio, but for your API logs. KPIs, filtered requests, click-through waterfall with redacted bodies. No auth gymnastics, no embedding. → Setup walkthrough

Option B — embedded in your app

// app/apitrail/[[...path]]/page.tsx
import { Dashboard } from '@apitrail/dashboard'
import '@apitrail/dashboard/styles.css'

export const dynamic = 'force-dynamic'

export default async function Page({ params }: { params: Promise<{ path?: string[] }> }) {
  return (
    <Dashboard
      params={params}
      auth={async () => (await getSession())?.user?.role === 'admin'}
    />
  )
}

Option C — CLI

pnpm dlx @apitrail/cli status --limit 20

---

🎯 Features

• ⚡ 60-second setup via apitrail install. Works with pnpm, npm, yarn, bun.
• 🔥 Edge-safe by construction — @apitrail/postgres lazy-loads pg so your middleware doesn't crash in production.
• 🛡️ PII masking by default — password, token, authorization, api_key, credit_card, cvv, ssn, and more. Add your own. Matches in bodies, headers, and query strings.
• 🔗 Query-string secret stripping — ?api_key=SECRET is split before storage; the path never holds secrets.
• 🌊 Full child-span waterfall — same tree you'd see in Chrome DevTools, rendered right in studio.
• 🎚️ Per-category sampling — keep 100% of errors and slow requests, 10% of successes. Tunable.
• 🚫 Studio refuses to expose itself — binding to non-loopback requires --auth-basic. Constant-time comparison.
• 🗄️ Database query timings — zero config. Install @opentelemetry/instrumentation-pg and apitrail auto-detects it on startup. Every SQL query appears in the waterfall with its duration. Same for fetch, Redis, MongoDB, AWS-SDK, GraphQL — just install the package, no code change. → guide
• 🧊 Zero runtime deps in the core beyond OTEL primitives. ~6 KB gzipped.
• 🧪 101 tests across the monorepo. Biome-strict lint. Published with npm provenance.

---

📦 Packages

All packages live in the @apitrail/* npm organization.

Package	Description	Version
@apitrail/core	Core — register(), defineConfig, OTEL processor, body capture, masking, auto-instrument
@apitrail/postgres	Postgres storage adapter — edge-safe, Supabase-ready
@apitrail/cli	apitrail install / init / status / drop
@apitrail/studio	Standalone dev dashboard — Prisma-Studio-style
@apitrail/dashboard	Embeddable Server Component dashboard

---

📚 Documentation

• 👉 INTEGRATING.md — canonical config reference, edge-safe patterns, troubleshooting. Start here.
• 🖥️ docs/STUDIO_SETUP.md — studio setup: local, LAN, Docker, systemd, reverse proxy.
• 🔐 SECURITY.md — threat model, built-in controls, deployment patterns.
• 🤖 AGENTS.md — for AI coding agents contributing to this repo.
• 📖 llms.txt — structured index for LLM consumers (llmstxt.org).

---

🗺️ Roadmap

• OTEL-based capture with body/header + child-span waterfall
• PII masking with sensible defaults
• Per-category sampling (success / error / slow)
• Query-string secret stripping
• Postgres adapter (Supabase / Neon / RDS / self-hosted)
• CLI with install wizard, init, status, drop
• Standalone studio (Prisma-Studio-style)
• Embeddable Server Component dashboard
• Security hardening (headers, auth, rate limit, validation)
• Live tail over SSE in studio
• Full-text search in bodies
• Error grouping by fingerprint
• MongoDB, MySQL, SQLite storage adapters
• Framework adapters beyond Next.js (Hono, Elysia, Remix, Fastify, Express)
• Hosted docs site at apitrail.io

---

🤝 Contributing

Contributions are welcome. See CONTRIBUTING.md for the dev loop, coding style, and release flow.

_{Made with contrib.rocks.}

Areas that could use help

• 🧩 Additional storage adapters (MongoDB, MySQL, SQLite, BigQuery, ClickHouse)
• 🌐 i18n for the dashboards
• 📊 Chart components for the studio
• 🎨 Theming / palette customization
• 📝 Docs site (Nextra / Fumadocs)

---

💬 Community

• 🐛 Report a bug
• 💡 Request a feature
• 🔐 Report a vulnerability (do not open a public issue)

---

📈 Star history

---

📄 License

MIT © Osharim and contributors. Built for people who like owning their data.

_{If apitrail saves you a Sentry bill, please ⭐ the repo.}