# Zipkin

Send Spice traces of SQL queries, AI chat completions, tool calls, and dataset refreshes to Zipkin for distributed tracing.

Spice supports distributed tracing by integrating with Zipkin and compatible tracing systems. Traces capture completed tasks (SQL queries, AI chat completions, tool calls, dataset refreshes), recording execution time, inputs, outputs, and errors.

## Configuration

Enable Zipkin tracing by configuring the `runtime.tracing` section in your project's `spicepod.yaml`:

```yaml
runtime:
  tracing:
    zipkin_enabled: true
    zipkin_endpoint: "http://your_zipkin_host:9411/api/v2/spans"
```

| Parameter | Default | Description |
| - | - | - |
| `zipkin_enabled` | `false` | Enables or disables Zipkin trace export. |
| `zipkin_endpoint` | None | Required if enabled. The `/api/v2/spans` endpoint on your Zipkin instance. |

Trace data will be available in the Zipkin UI at `http://your_zipkin_host:9411`. See the [Zipkin Quickstart](https://zipkin.io/pages/quickstart) to run a test server.

## Trace Information

A trace in Spice represents a completed task. Each trace is a unique span recording execution time, inputs, outputs, and errors.

| Field | Description |
| - | - |
| `trace_id` | Unique identifier for the trace |
| `span_id` | Unique identifier for the span |
| `task` | Task type (e.g. `sql_query`, `text_embed`, `health`) |
| `start_time` | When the task started |
| `end_time` | When the task completed |
| `execution_duration_ms` | Execution duration in milliseconds |
| `error_message` | Error details, if the task failed |

Example trace data:

```
trace_id                          | task                 | execution_duration_ms | error_message
----------------------------------|----------------------|-----------------------|------------------------------------------
687e0970f8c49d19c5a08764ea2d4dc1  | text_embed           | 16132.4               |
1e881188e5fd252b26adb8a8d838efb8  | sql_query            | 6.1                   |
701874d7282dd47791e7519b343a9694  | acceleration_refresh | 0.4                   |
3c75d16b6b4b8da98c551d115e1c049c  | sql_query            | 0.1                   | SQL error: ParserError("Expected:...")
```

For more details, see [Task History](https://spice.ai/docs/features/observability/task-history).

See also:

- [Portal Monitoring](https://spice.ai/docs/cloud/monitoring/portal) - Built-in monitoring in the Spice.ai portal
- [Metrics API](https://spice.ai/docs/cloud/api/metrics) - Prometheus-compatible metrics endpoint