Trace sinks

A trace sink is any consumer of a stitch's event stream — reach for one when you want every start → progress → drift → result → done teed somewhere durable. Tracing is off by default: a stitch makes its call and writes nothing, prints nothing (no side effects by default). You turn it on per stitch with the trace field, globally with an env var, or handle events yourself by iterating .stream().

Example

Opt in per stitch with the trace field — 'console' for the colored stderr stream, or fileSink(path) for JSONL on disk:

import { fileSink, stitch } from 'stitchapi';

// Colored one-line-per-event stream to stderr.
const search = stitch({
    baseUrl: 'https://api.example.com',
    path: '/search',
    trace: 'console',
});

// JSONL appended to a file you name.
const report = stitch({
    baseUrl: 'https://api.example.com',
    path: '/report',
    trace: fileSink('./runs/today.jsonl'),
});

Or wire it globally by environment variable — handy for turning tracing on without touching code:

# Colored stream to stderr.
STITCH_TRACE_CONSOLE=1 node run.js

# Append JSONL to a path (off unless set).
STITCH_TRACE_FILE=./runs/today.jsonl node run.js

# ALSO fan the same events to an OTLP collector.
STITCH_EXPORT=otlp node run.js

# Turn file tracing OFF: 0, false, or an empty value disable it (no file is written).
STITCH_TRACE_FILE=0 node run.js

# Capture full request/response bodies (the JSONL truncates them to 2048 chars by default).
STITCH_TRACE_MAX_BODY=full node run.js

A stitch-local trace wins over the environment: trace: false forces tracing off even when the env vars are set.

To consume events as your own sink, iterate the stream — that's the public seam for custom handling:

import { stitch } from 'stitchapi';

const search = stitch({ baseUrl: 'https://api.example.com', path: '/search' });

for await (const event of search({ query: { q: 'mango' } }).stream()) {
    if (event.type === 'drift')
        console.log(event.finding.level, event.finding.path);
    if (event.type === 'result') console.log(event.data);
}

Options

The trace field accepts:

When trace is unset, four env vars control the built-in sink: STITCH_TRACE_CONSOLE=1 turns on the colored stderr stream; STITCH_TRACE_FILE=<path> appends JSONL to that path (off when unset, 0, or false); STITCH_EXPORT=otlp adds OTLP as one more sink fed from the same events — see OTLP export; and STITCH_TRACE_MAX_BODY tunes body truncation (full to capture whole bodies, or a character cap).

To build sinks in code, consoleSink() and fileSink(path) return the single-purpose sinks, createTrace({ console, file }) returns one that does both, and multiplex(a, b, ...) fans one event stream out to several sinks at once. All are exported from stitchapi.

Logging to a host logger

Already running pino, winston, or just console? loggerSink(logger) bridges the event stream straight onto it — no JSONL file, no OTLP collector. It is logger-agnostic (anything with error / warn / info / debug methods satisfies the LoggerLike shape) and payload-free: it logs only metadata — name, method, scrubbed URL, status, attempt counts, drift path/level, timing — never event.input, event.data, or a streamed delta chunk.

import { loggerSink, stitch } from 'stitchapi';

// `console` already satisfies LoggerLike; swap in `pino()` / a winston logger / a
// Nest `Logger` and nothing else changes.
const search = stitch({
    baseUrl: 'https://api.example.com',
    path: '/search',
    trace: loggerSink(console),
});

Each StitchEvent maps to a level:

Override any per-type level with levels — for example, demote the happy-path result to debug so production logs stay quiet until something drifts or errors:

import { loggerSink, stitch } from 'stitchapi';

const search = stitch({
    baseUrl: 'https://api.example.com',
    path: '/search',
    trace: loggerSink(console, { levels: { result: 'debug' } }),
});

Turning tracing off

There are two off switches, both of which disable the built-in sinks:

// Per-stitch: `trace: false` disables ALL built-in sinks for this stitch and wins
// over every STITCH_TRACE_* env var. (A `TraceSink` value replaces them instead.)
const quiet = stitch({
    baseUrl: 'https://api.example.com',
    path: '/health',
    trace: false,
});

Globally, set STITCH_TRACE_FILE to 0, false, or an empty string to turn file tracing off — these are treated as the off switch, not as a path, so no file named 0 or false is ever written to the working directory.

Default secret redaction

Before any event is written to the built-in JSONL (or console) sink, header values for a fixed denylist are replaced with the literal [REDACTED], matched case-insensitively wherever headers appear in the event payload (the start event's input headers, response headers, and so on):

• authorization
• proxy-authorization
• cookie
• set-cookie
• x-api-key

So a call carrying authorization: 'Bearer …' traces as "authorization":"[REDACTED]" — the raw secret never reaches disk. Redaction happens at the sink boundary, so the live request still sends the real header; only the trace copy is scrubbed.

The same boundary scrubs URLs: a start event's resolved URL has any userinfo (https://user:pass@host) removed and the values of secret-bearing query params (api_key, access_token, signature, …) replaced with REDACTED — in both the JSONL url field and the OTLP url.full attribute. The matching keys in the start event's structured input.query are redacted the same way, so the two views can't disagree; benign params (page, sort) survive for observability.

Need to redact a non-standard auth header (say x-auth-token)? Widen the denylist — you can extend it but never shrink it — with redactHeaders:

import { fileSink, stitch } from 'stitchapi';

const search = stitch({
    baseUrl: 'https://api.example.com',
    path: '/search',
    trace: fileSink('./runs/today.jsonl', {
        redactHeaders: ['x-auth-token', 'x-session-id'],
    }),
});

A TraceSink is just { handle(event, ctx), flush?() } — implement those two and you have a custom consumer you can pass to trace or multiplex. The same shape backs the console, JSONL, and OTLP sinks, which is why all three come from one source without the call site knowing. See Reference → Helpers for the exported building blocks and Reference → Event types for the StitchEvent union a sink receives.

Body truncation and full capture

To keep one large response from bloating the log — and to limit how much payload is persisted by default — the built-in JSONL sink truncates the request body (the start event) and the response value (the result event) once their JSON encoding passes a character cap. The oversized value is replaced with a compact marker:

{ "truncated": true, "bytes": 51234, "preview": "{\"items\":[{\"id\":1,…" }

preview is the first maxBodyBytes characters of the (already header-redacted) JSON, so you keep a readable head of the payload without storing all of it. The default cap is 2048 characters; 0 keeps only the marker, no preview.

Truncation bounds size — it is not field-level redaction, and a preview can still contain a body-embedded secret. Header and URL secrets are redacted (above) regardless of the cap.

Opt into full capture — the whole body, untruncated — when you need it, with maxBodyBytes: false on the file sink:

import { fileSink, stitch } from 'stitchapi';

const report = stitch({
    baseUrl: 'https://api.example.com',
    path: '/report',
    // false = capture the whole body; a number sets a custom character cap.
    trace: fileSink('./runs/today.jsonl', { maxBodyBytes: false }),
});

Or globally, without touching code, via the env knob the built-in sink reads:

# Whole bodies, no truncation.
STITCH_TRACE_MAX_BODY=full node run.js

# A custom character cap (here 8 KB).
STITCH_TRACE_MAX_BODY=8192 node run.js

See also