rs2 / restspace

9.6 Tracing: X-Trace-Id and correlating to logs

Every request gets a trace id, and that id is the thread connecting a response, its log lines, and any internal hops it spawned. It's the single most useful thing to capture when something goes wrong.

X-Trace-Id on every response

The server echoes an X-Trace-Id header on every response. It matches the traceId field in:

  • a problem+json error body (9.2), and
  • the structured log records for that request (Part 10).

So given a trace id, you can pull up exactly what happened on the server for that one request.

One trace, many spans

A single external request can fan out into internal hops — a pipeline calling several mounts, a custom service using a granted capability. The runtime logs a boundary record at each hop, all sharing the request's traceId but each with its own spanId. That gives you a tree: the external request and every internal call it caused, correlated under one id.

Looking a trace up

If a log service is mounted (Part 10), you can fetch every record for a trace:

GET /<logmount>/<traceId>

This returns all records for that request — the boundary log, any service logs, and any custom-service console.log/ctx.log lines — in one place. For debugging a deployed custom service, this is the equivalent of reading the console for that exact request (8.8).

The debugging loop

  1. A request fails; note the X-Trace-Id from the response (or traceId in the error body).
  2. GET /<logmount>/<traceId> (or search your log platform by that id).
  3. Read the boundary log (status, duration, error code) and any service/sandbox lines stamped with the same trace.

Why this is built in

Tracing isn't bolted on per service — it's emitted at the host's single dispatch choke point, so it's uniform and complete by construction (every request, every hop, no service can forget to log). That's the same throughline as the rest of the runtime: cross-cutting concerns live in the host.

That completes the cross-cutting HTTP behavior. Part 10 turns to operating a node — server config, multi-tenancy, logging sinks, and safe live config edits.

← Previous: 9.5 Limits and containment · Manual home · Next: Part 10 — 10.1 Server config in depth →