Skip to main content

trace

Provides a user-friendly trace stack into an operation that occurred in Spice. This command retrieves and displays task execution traces from the runtime.task_history table.

Usage​

spice trace [task] [flags]

task - The name of the task whose trace is requested. Supported tasks include:

  • accelerated_refresh
  • ai_chat
  • ai_completion
  • sql_query
  • nsql
  • tool_use::document_similarity
  • tool_use::list_datasets
  • tool_use::sql
  • tool_use::table_schema
  • tool_use::sample_data
  • tool_use::sql_query
  • tool_use::memory
  • vector_search

These tasks are from the task column in the Spice SQL runtime.task_history table.

Flags​

  • --trace-id Retrieve the trace with the given trace ID (the column trace_id from runtime.task_history).
  • --id Retrieve the trace with the given id label (i.e. the task has a valid id within the labels column of runtime.task_history).
  • --api-key Specify the API key for authentication.
  • --include-output: Include, as an additional column, the captured output to each span (i.e. the captured_output column from runtime.task_history). Note: If captured outputs are not being stored, this will return an empty row.
  • --include-input: Include, as an additional column, the input to each span (i.e. the input column from runtime.task_history).

The latest trace for the task will be used if neither --trace-id nor --id is specified.

Examples​

Retrieve the trace for the last text-to-SQL operation​

spice trace nsql

Retrieve the trace for a specific task by ID​

spice trace ai_chat --id chatcmpl-At6ZmDE8iAYRPeuQLA0FLlWxGKNnM

Retrieve a trace by trace-id​

spice trace sql_query --trace-id d5c6f1eed9f27257

Output Example​

TREE                   STATUS DURATION   TASK
a97f52ccd7687e64       ✅       673.14ms ai_chat
  ├── 4eebde7b04321803 ✅         0.04ms tool_use::list_datasets
  └── 4c9049e1bf1c3500 ✅       671.91ms ai_completion

This output represents a structured trace of executed tasks.

Output Example (with --include-output)​

TREE                   STATUS DURATION   TASK                    OUTPUT
a97f52ccd7687e64       ✅       673.14ms ai_chat                 The capital of New York is Albany.
  ├── 4eebde7b04321803 ✅         0.04ms tool_use::list_datasets []
  └── 4c9049e1bf1c3500 ✅       671.91ms ai_completion           [{"content":"The capital of New York is Albany.","refusal":null,"tool_calls":null,"role":"assistant","function_call":null,"audio":null}]