Debugging with trace

When a request goes wrong, the fastest path to a diagnosis is the correlationId that ties every action, event, reaction, and projection in the call tree together. This recipe shows the loop: reproduce → grab the id → inspect via CLI → drill in via Studio.

1. Run the wire

nwire dev

2. Reproduce the call

curl -i -X POST http://localhost:3000/posts \
  -H 'content-type: application/json' \
  -d '{ "title": "hello", "body": "first post" }'

Every Nwire response sets the x-correlation-id header:

HTTP/1.1 422 Unprocessable Entity
x-correlation-id: 01J9XW8C7K4F1ZD5T6QH3Y8M2E

3. Inspect from the CLI

nwire trace --correlation 01J9XW8C7K4F1ZD5T6QH3Y8M2E

Sample output:

correlationId: 01J9XW8C7K4F1ZD5T6QH3Y8M2E
┌──────┬───────────────────────┬─────────────────────────┬─────────┬────────┐
│ step │ kind                  │ name                    │ ms      │ status │
├──────┼───────────────────────┼─────────────────────────┼─────────┼────────┤
│ 1    │ action.dispatched     │ posts.publish           │   0.4   │ ok     │
│ 2    │ handler.start         │ posts.publish.handler   │   1.1   │ ok     │
│ 3    │ event.fired           │ post.drafted            │   1.3   │ ok     │
│ 4    │ projection.write      │ posts.byAuthor          │   2.0   │ ok     │
│ 5    │ reaction.start        │ notify-followers        │   2.4   │ ok     │
│ 6    │ action.dispatched     │ notifications.fanout    │   2.6   │ FAIL   │
│ 7    │ error                 │ ValidationError         │   2.7   │ FAIL   │
└──────┴───────────────────────┴─────────────────────────┴─────────┴────────┘

4. Open Studio on the same id

http://localhost:7777/trace?correlationId=01J9XW8C7K4F1ZD5T6QH3Y8M2E

Studio renders the same tree as a graph and lets you click the failing node to see its envelope, input, and error.

See also

• Trace topology diagram
• Telemetry kinds
• CLI reference