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.

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​

[d5c6f1eed9f27257] ( 3077.45ms) ai_chat
  ├── [16eb97d757e4ea47] (    0.85ms) tool_use::list_datasets
  ├── [ece97973668bd54a] ( 1651.14ms) ai_completion
  ├── [96fe526b54330e95] (    0.62ms) tool_use::get_readiness
  └── [8aa2bf4c94f42ba2] ( 1420.09ms) ai_completion

This output represents a structured trace of executed tasks.