spans

Creates, updates, deletes, gets or lists a spans resource.

Overview

Name	spans
Type	Resource
Id	aws.qconnect.spans

Fields

The following fields are returned by SELECT queries:

list_spans

Name	Datatype	Description
assistant_id	string	UUID of the Connect AI Assistant resource (pattern: <code>[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}</code>)
attributes	object	Span-specific contextual attributes
end_timestamp	string (date-time)	Operation end time in milliseconds since epoch
origin_request_id	string	The origin request identifier for end-to-end tracing.
parent_span_id	string	Parent span identifier for hierarchy. Null for root spans. (pattern: <code>[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}</code>)
request_id	string	The service request ID that initiated the operation (pattern: <code>[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}</code>)
session_id	string	UUID of the Connect AI Session resource (pattern: <code>[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}</code>)
span_id	string	Unique span identifier (pattern: <code>[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}</code>)
span_name	string	Service-defined operation name (pattern: <code>[a-zA-Z0-9\s_.,-]+.*</code>)
span_type	string	Operation relationship type (CLIENT, SERVER, INTERNAL)
start_timestamp	string (date-time)	Operation start time in milliseconds since epoch
status	string	Span completion status (OK, ERROR, TIMEOUT)
status_description	string	Human-readable error description when status is ERROR or TIMEOUT

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_spans	select	assistant_id, session_id, region	nextToken, maxResults	Retrieves AI agent execution traces for a session, providing granular visibility into agent orchestration flows, LLM interactions, and tool invocations.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
assistant_id	string	UUID or ARN of the Connect AI Assistant resource
region	string	AWS region (default: us-east-1)
session_id	string	UUID or ARN of the Connect AI Session resource
maxResults	integer	Maximum number of spans to return per page
nextToken	string	Pagination token for retrieving the next page of results

SELECT examples

list_spans

Retrieves AI agent execution traces for a session, providing granular visibility into agent orchestration flows, LLM interactions, and tool invocations.

SELECT
assistant_id,
attributes,
end_timestamp,
origin_request_id,
parent_span_id,
request_id,
session_id,
span_id,
span_name,
span_type,
start_timestamp,
status,
status_description
FROM aws.qconnect.spans
WHERE assistant_id = '{{ assistant_id }}' -- required
AND session_id = '{{ session_id }}' -- required
AND region = '{{ region }}' -- required
AND nextToken = '{{ nextToken }}'
AND maxResults = '{{ maxResults }}'
;