Skip to main content

Correlations

The Correlations screen lets you see the audit events of your tenant grouped by trace, run or session, so you can follow one request or one agent run across every service it touched. Portal path: /audit/correlations (menu Audit > Correlations). Auditors, security officers and tenant administrators use it during an investigation.

What the screen shows​

AreaContent
FiltersTrace id, Run id, Session id.
Correlations tableOne row per correlation key, most recent first, up to 50: Key, Key type (trace_id, run_id, session_id), Events, Actions (distinct actions of the group), First, Last.
Empty stateNo correlation: filter by trace id or run id.

Without a filter, the server groups the events by trace id, by run id (taken from the event details or from a run resource) and by session id.

Actions​

Button or actionWhat it doesAPI callRoles
FilterSends the filters filled in.GET /v1/audit/correlations (trace_id, run_id, session_id, limit)auditor, security_officer, tenant_admin, platform_admin
Refresh (round arrow icon)Reloads the groups.GET /v1/audit/correlationsSame roles
Events (row menu, rows of type trace_id)Lists the audit events of the trace in a side panel titled Events (JSON).GET /v1/audit/events (trace_id)Same roles

Roles​

RoleAccess
auditor, security_officer, tenant_adminOpen the screen (portal/src/lib/nav-access.ts) and read the correlations (READERS of services/control-plane/src/eai/domains/observability/audit_api.py).
platform_adminSame rights, inside a tenant (tenant_required otherwise).
Other rolesThe entry is hidden; the page shows Your roles do not open this page.
note

With a filter, GET /v1/audit/correlations returns one correlation bundle (key, trace_ids, audit_events, usage_events, runs, spans, multimodal_jobs, counts) instead of a list of groups. The table of the screen reads only the list of groups, so it shows No correlation after a filter. To read the events of one trace, use the Events action of its row, or the Trace id filter of Events and chain.

Typical tasks​

Follow a request across the services​

  1. Open the screen. The list shows the latest correlation keys. Go to Audit > Correlations. Expected result: the table lists keys of type trace_id, run_id and session_id. If it fails: Your roles do not open this page means you need the auditor role.
  2. Find the trace. Look for the trace id in the Key column (copied from Traces, for example). The Actions column shows what happened. Expected result: the row of the trace, with its event count and its first and last time. If it fails: click Refresh; the list keeps the 50 most recent keys.
  3. List its events. Open the row menu and choose Events. Expected result: the side panel shows the audit events of the trace as JSON. If it fails: the action exists only on rows of type trace_id; for a run, filter Actor or Resource in Events and chain.

Review the activity of an agent run​

  1. Spot the run. Look for the row whose Key type is run_id and whose Key is the run id. Expected result: Events, First and Last give the size and the time span of the run. If it fails: the run id comes from the event details; a run that wrote no audit event is not listed.
  2. Open the run. Go to Runs to see its steps and its cost. Expected result: the run detail matches the time span of the group. If it fails: check that you are in the tenant of the run.

Troubleshooting​

SymptomCauseFix
No correlation right after FilterWith a filter, the server returns a bundle that the table does not list.Clear the filters and use the Events action, or the Trace id filter of Events and chain.
No correlation without filterNo audit event carries a trace, run or session id.Check that the SDK and the gateways propagate the trace context.
No Events action on a rowThe row is of type run_id or session_id.Use Events and chain.
Error forbidden (HTTP 403)No reading role of the audit trail.Ask for the auditor role.
Error tenant_required (HTTP 403)Platform administrator without a tenant.Sign in to a tenant.