Tracing your code

Tracepanel records your framework and libraries on its own. To see your own code in a trace, wrap it in span(). To trace work that isn't a request, such as a script or a scheduled job, wrap it in trace().

span()Copy Anchor Link

span() runs a function as a step of the current trace. The SQL, calls and logs it makes go inside the step in the call tree:

import { span } from "@tracepanel/js";

const rows = await span("load stale rows", () => loadStaleRows());

It returns what the function returns. An error the function throws marks the step as failed and goes on to your code. A third argument adds attributes to the step:

await span("charge", () => charge(order), { "order.id": order.id });

trace()Copy Anchor Link

trace() runs a function as a trace of its own. The console lists it under Jobs:

import { span, trace } from "@tracepanel/js";

await trace("nightly cleanup", async () => {
  await span("load stale rows", () => loadStaleRows());
});

Inside a request, trace() is a step of the request, as span() is. The kind option makes the trace a task, which the console lists under Tasks, and attrs adds its attributes:

await trace("send digest", () => sendDigest(user), {
  kind: "task",
  attrs: { "task.queue": "mail" },
});

Run a script with Tracepanel on through the tracepanel command:

npx tracepanel run node script.js

Outside development, span() and trace() run their function and nothing else.