sentry

@stitchapi/sentry

A Sentry TraceSink for StitchAPI. The logger sinks (@stitchapi/pino, core's loggerSink) and the OTLP bridge cover logs and traces; Sentry's model is different — a trail of breadcrumbs leading up to a captured error. This sink maps the stitch event stream onto it.

Routine events become breadcrumbs (category stitch); an error event is captured as a Sentry issue with the call's context, so the breadcrumb trail attaches automatically.

Bring your own Sentry. The sink imports no SDK — it talks to a small structural surface that @sentry/node, @sentry/browser, @sentry/react, and friends all satisfy. So there's no @sentry/* dependency, and a test double is a drop-in.

Install

pnpm add @stitchapi/sentry@rc stitchapi@rc

stitchapi is the only peer dependency. Pass whichever @sentry/* SDK your app already runs.

Usage

import * as Sentry from '@sentry/node';
import { sentrySink } from '@stitchapi/sentry';
import { seam } from 'stitchapi';

const api = seam({
    baseUrl: 'https://api.example.com',
    trace: sentrySink(Sentry),
});

The same sink works on a single stitch — stitch({ trace: sentrySink(Sentry) }).

What it sends

Event	Sentry
error	captureMessage (level error) + an error breadcrumb
progress (retry/circuit)	breadcrumb, level warning
progress (throttle/paginate)	breadcrumb, level debug
drift	breadcrumb (level follows the finding); captured with capture: { drift: true }
start / result / done	breadcrumb only when lifecycle: true (off by default)
delta / info	never sent (raw response data / strategy announcements)

Options: { lifecycle?, capture?: boolean | { errors?, drift? } }. capture: false disables both errors and drift capture (breadcrumbs still flow); capture: true/omitted resolves to the documented defaults (errors: true, drift: false); pass the envelope to set them independently.

Note

The same lifecycle option in @stitchapi/pino defaults to true — a deliberate divergence: Sentry breadcrumbs/events cost quota, while Pino log lines are cheap and level-filtered.

Safe on a secret-bearing seam

A custom TraceSink receives the raw event — core only redacts inside its own built-in sinks. This sink therefore sends metadata only: the stitch name, method, redacted URL (query stripped — it can carry ?api_key=…), status, attempt counts, drift path/level/change, phase, and timing. It never sends event.input (headers still hold the live authorization/cookie), the response data, or a delta chunk.

License

Apache-2.0

Contributing

Issues and pull requests are welcome — see the contributing guide for local setup, the verify gate, and how to open a PR against main.