Skip to content
Olyx

olyx debug

List recent traces or inspect recorded requests, provider attempts, and responses.

Inspect local trace data without contacting model providers. Debug does not require provider credentials.

Synopsis

Section titled “Synopsis”
olyx debug [TRACE_ID] [--config FILE]

List recent traces

Section titled “List recent traces”
Terminal window
olyx debug
olyx debug --config examples/olyx.json

Without an ID, debug returns a JSON object whose data array contains up to 100 recent traces. Use the same configuration and database that recorded the request.

Inspect a trace

Section titled “Inspect a trace”
Terminal window
olyx debug TRACE_ID

A trace shows the input and response, models tried, errors, status, and how long each attempt took. Cost estimates use the provider rates you configure. Failed requests can also have traces; use the trace ID in the error message.

Debug reads the saved request and response. It does not call the model again. Use replay when you want a new response.

Save and filter a trace

Section titled “Save and filter a trace”
Terminal window
olyx debug TRACE_ID > trace.json

With the optional jq utility, inspect the recorded attempts:

Terminal window
jq '.steps[] | {model, allowed, latency_ms}' trace.json

The saved file contains application inputs and outputs; review it before sharing.

Failed requests

Section titled “Failed requests”

For failed traces, debug writes a failure summary and recovery hint to stderr before printing the full trace JSON on stdout. The JSON includes a top-level diagnostic with an error code, trace ID, and provider details with credentials removed where available. For traces recorded before these details were added, inspect the saved provider attempts. See doctor and diagnostics for error codes and fallback behavior.

Storage behavior

Section titled “Storage behavior”

Debug applies the configured retention period when it opens the database. It can create missing database files and tables, delete expired traces, and mark abandoned requests as failed after a process stops. Back up the database before using a configuration with a shorter retention period.

trace_not_found means the ID is absent from the selected database. Check the configuration path, database location, retention, and whether the original route used :memory: storage.

A recovered trace uses request_interrupted. Its saved steps remain available, and recovery does not call the provider again. See crash recovery for process-lock behavior and older traces.

Inspect configuration separately

Section titled “Inspect configuration separately”
Terminal window
olyx inspect
olyx check olyx.json

inspect shows the configuration path and whether the file exists. check validates the file. Neither command reads traces. See the CLI reference for output and exit status.