Traces
The Traces screen lets you list the recent traces of your tenant, one per root span, with their duration,
status, span and error counts and the run they belong to, and open the spans of one trace. Portal path:
/observability/traces (menu Observability > Traces). Support engineers and developers use it to find a
slow or failing request.
What the screen shows
| Area | Content |
|---|---|
| Filters | Status (ok, error, unset), Service, Run id. |
| Traces table | Columns: Start, Name, Service, Status, Duration (ms), Spans, Errors, Run id, Trace id. Newest first, the last 24 hours, up to 50 traces. |
| Detail panel | A click on a row loads the trace: every span (name, kind, service, times, duration, status, allowed attributes, tokens, cost), the span count, the errors and the audit events of the trace. |
| Empty state | No trace in the window: traces appear once the SDK or the gateways send spans (POST /v1/telemetry/spans). |
Actions
| Button or action | What it does | API call | Roles |
|---|---|---|---|
| Filter | Applies the filters filled in. | GET /v1/telemetry/traces (status, service, run_id) | platform_admin, tenant_admin, auditor, viewer, support_engineer |
| Refresh (round arrow icon) | Reloads the list. | GET /v1/telemetry/traces | Same roles |
| Click on a row | Opens the detail panel of the trace. | GET /v1/telemetry/traces/{trace_id} | Same roles |
| Retry (error panel) | Sends the request again. | GET /v1/telemetry/traces | Same roles |
Roles
| Role | Access |
|---|---|
platform_admin, tenant_admin, auditor, viewer, support_engineer | Open the screen and read the traces of their tenant (ROLES of services/control-plane/src/eai/domains/observability/slo.py, checked in services/control-plane/src/eai/domains/observability/live.py). |
| Other roles | The Observability section is hidden; the page shows Your roles do not open this page. |
The route needs a tenant context (tenant_required otherwise).
Typical tasks
Find the failing requests of the last day
- Filter on errors. Choose
errorin Status and click Filter. Expected result: the table lists the traces whose root span failed, newest first. If it fails: No trace in the window means no failing trace in the last 24 hours. - Open a trace. Click the row to load its spans.
Expected result: the panel lists the spans; the span in error shows its
statusand its allowed attributes. If it fails:not_foundmeans the trace has no stored span nor audit event any more. - Follow it in the audit trail. Copy the Trace id and filter on it in Events and chain. Expected result: the audit events of the request are listed. If it fails: check that the trace id has 32 hexadecimal characters.
List the traces of an agent run
- Filter on the run. Paste the run id in Run id and click Filter. Expected result: the traces of the run are listed with their duration and error count. If it fails: the run may be older than 24 hours; the list covers the last day only.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| No trace in the window | No span received in the last 24 hours, or the filters exclude everything. | Remove the filters; check that the SDK sends spans with POST /v1/telemetry/spans. |
Error invalid_request (HTTP 400) when opening a trace | The trace id is not made of 32 hexadecimal characters. | Open the trace from the table. |
Error not_found (HTTP 404) in the detail panel | No span nor audit event left for this trace. | The data has expired; use the list again. |
Error forbidden or tenant_required (HTTP 403) | No observability role, or no tenant. | Ask for the viewer or support_engineer role in your tenant. |