@breadcrumb-sh/core

Embeddable LLM tracing for TypeScript apps. Your database, your deployment, your UI.

Breadcrumb captures your LLM calls (tokens, model, cost, cached and reasoning tokens), nests spans into traces, and writes them to your own SQLite or Postgres. You mount a fetch-native handler into your app and render the dashboard from @breadcrumb-sh/react, or build your own UI on the headless API here. Built on OpenTelemetry, with native support for the Vercel AI SDK.

Install

npm i @breadcrumb-sh/core pg              # Postgres
npm i @breadcrumb-sh/core better-sqlite3  # SQLite

pg and better-sqlite3 are optional peer dependencies. Install only the driver for the database you use.

Setup

Create one instance and mount its handler:

// lib/breadcrumb.ts
import { breadcrumb } from "@breadcrumb-sh/core";
import { postgres } from "@breadcrumb-sh/core/adapters";

export const bc = breadcrumb({
  database: postgres(process.env.DATABASE_URL!),
  basePath: "/api/breadcrumb",
  authorize: (req) => isAdmin(req),
  pricing: { "gpt-5": { input: 1.25, output: 10, cachedInput: 0.125 } },
});

Mount bc.handler (a (request: Request) => Promise<Response>) at basePath. It serves the JSON API, not a UI — the dashboard is a separate route rendering <BreadcrumbDashboard>. Framework bridges are provided:

// Next.js: app/api/breadcrumb/[...path]/route.ts
import { toNextHandler } from "@breadcrumb-sh/core/next";
export const { GET, POST, DELETE } = toNextHandler(bc);

// Node / Express
import { toNodeHandler } from "@breadcrumb-sh/core/node";
app.use("/api/breadcrumb", toNodeHandler(bc));

// Anything fetch-native (Hono, SvelteKit, …)
app.all("/api/breadcrumb/*", (c) => bc.handler(c.req.raw));

The schema is created automatically in development (migrations: "auto"). For production, generate migration files with the CLI and set migrations: "manual".

Instrumenting calls

Vercel AI SDK. bc.telemetry() returns settings for experimental_telemetry. Calls made inside a bc.trace() callback nest into the same trace automatically:

import { generateText } from "ai";

const { text } = await generateText({
  model: openai("gpt-5"),
  prompt,
  experimental_telemetry: bc.telemetry({ functionId: "generate-answer", userId, sessionId }),
});

functionId names the call and carries the cost attribution, wherever the call sits in the trace; userId and sessionId group runs by user and conversation.

Your own OpenTelemetry setup. If the app already has a tracer provider (@vercel/otel, NodeSDK, Sentry), register bc.spanProcessor on it and model spans reach breadcrumb without threading bc.telemetry() through every call:

registerOTel({ serviceName: "app", spanProcessors: [bc.spanProcessor] });

It stores only spans breadcrumb can read (ai.*, gen_ai.*, breadcrumb.*) unless shouldExport says otherwise, so a shared provider's HTTP and filesystem spans don't land in the trace table.

Manual tracing. bc.trace(name, attrs?, fn), with nested t.span(...):

await bc.trace("support-reply", { userId }, async (t) => {
  t.set({ input: prompt });
  const docs = await t.span("retrieve", { kind: "retrieval" }, async (s) => {
    const result = await search(prompt);
    s.set({ output: result });
    return result;
  });
  const answer = await callModel(prompt, docs);
  t.set({ output: answer, model: "gpt-5", inputTokens, outputTokens });
});

t.set() accepts model, provider, input/output, token counts (inputTokens, outputTokens, cachedInputTokens, cacheWriteTokens, reasoningTokens), an explicit cost, and metadata. A thrown error marks the span failed and rethrows.

On serverless or edge, call await bc.flush() (or waitUntil(bc.flush())) before the response returns so no spans are lost. Set flushMode: "sync" for those runtimes.

Entry points

| Import | Exports | | --- | --- | | @breadcrumb-sh/core | breadcrumb(), the Breadcrumb type, migration helpers (planMigration, renderMigrationSql, EMPTY_SCHEMA_STATE), and the full domain type contract. | | @breadcrumb-sh/core/adapters | sqlite(fileOrDb), postgres(connectionOrClient). | | @breadcrumb-sh/core/client | createBreadcrumbClient(), a typed browser fetch client mirroring bc.api. | | @breadcrumb-sh/core/kit | Headless UI helpers: traceModel, flowRows, selfTime, hotspots, asMessages, preview, and formatters (fmtCost, fmtTokens, fmtMs, …). | | @breadcrumb-sh/core/node | toNodeHandler() for Node/Express. | | @breadcrumb-sh/core/next | toNextHandler() for the Next.js App Router. |

Building your own dashboard

The server, the browser client, and the React hooks share one contract. Query the server directly from a React Server Component with bc.api (listTraces, listSessions, getTrace, stats, costSummary, …), use the typed client in the browser, or reach for @breadcrumb-sh/react hooks. Render with the headless kit:

import { traceModel, selfTime, asMessages, fmtCost } from "@breadcrumb-sh/core/kit";

const model = traceModel(spans);      // rows, scales, hotspots, totals
model.rows;                            // denoised, depth-indexed, ready to map
model.spots;                           // { errorId, slowestId, costliestId }
selfTime(span, children);              // extent minus what the children covered
const chat = asMessages(span.input);   // parse chat-shaped payloads
fmtCost(0.0042);                       // "$0.0042"

traceModel is what the shipped waterfall renders from, so a UI you build from scratch reads exactly the same numbers rather than reimplementing them.

Configuration

Key breadcrumb() options:

| Option | Default | Purpose | | --- | --- | --- | | database | required | A sqlite() or postgres() adapter. | | basePath | /breadcrumb | Where the handler is mounted, and what the dashboard's api prop points at. | | environment | VERCEL_ENV ?? NODE_ENV ?? development | Stamped on every span. | | authorize | none | Guards the query routes. Your dashboard page is yours to guard. | | ingest | none | { apiKey } enables HTTP ingest endpoints. | | pricing | none | USD per 1M tokens, keyed by model, for cost. | | retention | 90d | Per-environment retention windows. | | redact | none | Scrub or trim each span before storage. | | maxPayloadChars | 16384 | Truncate captured input/output (0 disables). | | flushMode | batch | sync for serverless/edge. | | migrations | auto | manual runs no runtime DDL. |

Breadcrumb ships no default prices. Omit pricing and only costs you set yourself are stored. See the full reference at breadcrumb.sh/docs/configuration.

License

MIT