> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ultra.security/llms.txt
> Use this file to discover all available pages before exploring further.

# Traces

> MCP operation trace records

Ultra records a **trace record** for every MCP operation. Traces capture the full lifecycle of a request — what was called, what arguments were sent, what came back, and how long it took.

## Trace Record Structure

Each trace record contains:

| Field            | Type     | Description                                               |
| ---------------- | -------- | --------------------------------------------------------- |
| `id`             | string   | Unique record identifier                                  |
| `trace_id`       | string   | OpenTelemetry trace ID (shared across related operations) |
| `span_id`        | string   | OpenTelemetry span ID (unique to this operation)          |
| `parent_span_id` | string   | Parent span for nested operations                         |
| `operation`      | string   | Operation type (see below)                                |
| `upstream`       | string   | Name of the upstream server that handled the request      |
| `name`           | string   | Tool, resource, or prompt name                            |
| `request`        | JSON     | Full request payload                                      |
| `response`       | JSON     | Full response payload                                     |
| `status`         | string   | `"success"` or `"error"`                                  |
| `error`          | string   | Error message (if status is error)                        |
| `duration`       | duration | How long the operation took (nanoseconds)                 |
| `timestamp`      | datetime | When the operation occurred                               |
| `metadata`       | map      | Additional key-value metadata                             |

### Multi-Tenant Fields

When connected to Ultra Hub, traces also include:

| Field          | Description                       |
| -------------- | --------------------------------- |
| `workspace_id` | Workspace this gateway belongs to |
| `gateway_id`   | This gateway's unique identifier  |

## Operation Types

| Type            | Description                       |
| --------------- | --------------------------------- |
| `tool_call`     | An MCP tool was invoked           |
| `resource_read` | An MCP resource was read          |
| `prompt_get`    | An MCP prompt was retrieved       |
| `tool_list`     | Client listed available tools     |
| `resource_list` | Client listed available resources |
| `prompt_list`   | Client listed available prompts   |

## Querying Traces

Traces are stored locally and can be queried through the dashboard.

### Dashboard

```bash theme={null}
ultra dashboard
```

The dashboard at `http://localhost:8080` provides:

* A list of all traces, sorted by timestamp
* Filtering by operation type, upstream server, status, and time range
* Full request/response payload inspection for each trace
* Duration and status breakdown
* A **Copy link** button on each trace to share a deep link to it, and an **Export** control to download the filtered trace list as CSV or JSON (see [Exporting table data](/observability/dashboard#exporting-table-data) and [Sharing links](/observability/dashboard#sharing-links))

### Aggregate Statistics

Aggregate statistics are computed over your traces:

* **Total requests** — Count of all operations
* **Success/error counts** — How many succeeded vs failed
* **Average duration** — Mean operation time
* **Requests by type** — Breakdown by operation type
* **Requests by server** — Breakdown by upstream server

## OpenTelemetry Compatibility

Trace IDs and span IDs follow the [W3C Trace Context](https://www.w3.org/TR/trace-context/) specification, making Ultra traces compatible with any OpenTelemetry-compatible backend. See [OTLP Export](/observability/otlp-export) for configuration.