How do I debug a run that went wrong?

You log with plain console.* and read the timeline the runtime already records. There is no tracer to register and no exporter to configure.

Inside a tool or a workflow step, the runtime captures every console.* line and stamps it with the run it belongs to, the trace of the invocation that produced it and the step that was executing. You thread no run id through your own code. Pass the variable data as an object rather than in the message. Only an object field stays filterable later:

console.info('email sent', { to, templateId }); // `to` is filterable
console.info('email sent to ' + to); // it is not

You get the run timeline without setting anything up. Each 'use step' appears with its timing, its result and every retry attempt. Agent turns show the tools the model invoked with their inputs and outputs, and calls through stackbone.ai record latency and token usage. A run parked on an approval reads as interrupted until the decision arrives.

You do not need Studio open to read any of it:

stackbone runs list
stackbone runs get <run-id>
stackbone logs tail --run <run-id> --follow

All three target the local-dev agent when you run them in your project. Add --agent <installationId> to read a deployed one instead.

Drop --follow and the tail prints what already happened, then exits, which is what you want in a script. --since, --until and --limit narrow it further. Once you know what went wrong, stackbone runs cancel <run-id> --yes stops a run still in flight. It changes state, so it wants --yes.

stackbone dev serves the same runs and the same timeline locally, so what you debug on your laptop matches what the deployed box does. When a CLI command itself fails, re-run it with --json and read error.code and error.suggestion.

A deployed box also writes every captured line to standard output as JSON, one object per line, so a log collector you already run picks them up. Point OTEL_EXPORTER_OTLP_ENDPOINT at a collector on the deployment and the box exports the logs and the run traces there too: send logs and traces to your own stack.

Read more

• Logging and observability: what the timeline records and how to read it.
• stackbone runs and stackbone logs: every verb and flag.
• When registration fails: for a box that never came up in the first place.