# div trace

> Print a trace's spans as a tree, print one span in full, or delete a trace.

## Synopsis

```text
div trace <trace> [flags]
```

Prints a trace as a tree of its spans. `<trace>` is a trace id, 32 hex characters, as [`div traces`](https://docs.divergentlabs.xyz/tracing/cli/traces.md) prints it. Reading needs the `traces:read` scope, and `--delete` needs `traces:write`. Keys from [`div login`](https://docs.divergentlabs.xyz/compute/cli/login.md) have both.

## Flags

| Flag | Description |
| --- | --- |
| `--span <span>` | Print one span in full: input, output, attributes and events. `<span>` is a span id, 16 hex characters. |
| `--delete` | Delete the trace, its spans and its scores. Spans sent for the trace in the next 24 hours are refused. |
| `--json` | Print the trace, with every span, or the span as JSON. |
| `--token <key>` | API key to use. |
| `--api-url <url>` | API URL to use. |

## Output

A summary line on stderr, then one span per line on stdout: offset from the trace's start, duration, kind, name indented under its parent, model, tokens in→out and span id. A span that ended in an error is red. A span whose parent was never received is listed at the top, marked `(parent not received)`.

```text
ai.generateText  4 spans  21ms  42→14 tokens  session sess-1
 0µs   21ms  agent       ai.generateText               gpt-4o-mini             42→14  7b800cb1cf808a76
 2ms   15ms  generation  ├ ai.generateText.doGenerate  gpt-4o-mini-2024-07-18  21→7   f3abe16fe4a6041c
13ms  279µs  tool        ├ ai.toolCall                                                2f307c70d2224e33
17ms    3ms  generation  ├ ai.generateText.doGenerate  gpt-4o-mini-2024-07-18  21→7   2763fbb4656f9f20
```

With `--span`, messages print as `role: text`, tool calls as `role: → name(arguments)` and their results as `role: ← result`:

```text
ai.generateText.doGenerate  generation  15ms
model gpt-4o-mini-2024-07-18  tokens 21→7  span f3abe16fe4a6041c  parent 7b800cb1cf808a76

Input
  system: Be brief.
  user: What is the weather in Amsterdam?

Output
  assistant: → weather({"city":"Amsterdam"})
```

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success. |
| `1` | The API rejected the request, such as a trace that does not exist. |
| `2` | Invalid arguments, such as an id that is not 32 hex characters. |

## Examples

```bash
div trace 4bf92f3577b34da6a3ce929d0e0e4736
div trace 4bf92f3577b34da6a3ce929d0e0e4736 --span f3abe16fe4a6041c
div trace 4bf92f3577b34da6a3ce929d0e0e4736 --json | jq '.spans | length'
div trace 4bf92f3577b34da6a3ce929d0e0e4736 --delete
```