Skip to content

Instrument your app

Where traces go

A sink is the function a finished trace is handed to. Send it to ChunkTrace, write it to a file, or both.

To ChunkTrace#

JavaScript
import { createProfiler, httpSink } from "@chunktrace/sdk";

const profiler = createProfiler({
  sink: httpSink({
    endpoint: "https://api.chunktrace.com",
    apiKey: process.env.CHUNKTRACE_KEY, // a full-access key
  }),
});

httpSink posts each trace to the HTTP API. It never throws. If the request fails, it logs a warning and your app carries on.

To handle failures yourself:

JavaScript
httpSink({ endpoint, apiKey, onError: (error) => logger.warn({ error }, "chunktrace ingest failed") });

Sending the same trace twice is safe. The server keeps one copy per trace_id.

To a file#

JavaScript
import { createProfiler, fileSink } from "@chunktrace/sdk";

const profiler = createProfiler({ sink: fileSink("./traces") });

Writes each trace to ./traces/<trace_id>.json. No account, no network. Read them back with the CLI:

Terminal
npx chunktrace diagnose traces/tr_mwk0ppb3_unefr7.json

To both#

JavaScript
import { fileSink, httpSink, multiSink } from "@chunktrace/sdk";

const sink = multiSink(fileSink("./traces"), httpSink({ endpoint, apiKey }));

Nowhere#

With no sink, traces are kept in memory on profiler.traces. That suits tests:

JavaScript
const profiler = createProfiler();
// … run a query …
expect(profiler.traces).toHaveLength(1);

Your own#

A sink is a function that takes a trace. It can be async.

JavaScript
const profiler = createProfiler({
  sink: async (trace) => {
    await queue.publish("traces", JSON.stringify(trace));
  },
});

The trace is plain JSON in the shape described in Trace schema.