2024/11/22 - AWS X-Ray - 8 new api methods
Changes AWS X-Ray introduces Transaction Search APIs, enabling span ingestion into CloudWatch Logs for high-scale trace data indexing. These APIs support span-level queries, trace graph generation, and metric correlation for deeper application insights.
Retrieves all indexing rules.
Indexing rules are used to determine the server-side sampling rate for spans ingested through the CloudWatchLogs destination and indexed by X-Ray. For more information, see Transaction Search.
See also: AWS API Documentation
Request Syntax
client.get_indexing_rules(
NextToken='string'
)
string
Specify the pagination token returned by a previous request to retrieve the next page of indexes.
dict
Response Syntax
{
'IndexingRules': [
{
'Name': 'string',
'ModifiedAt': datetime(2015, 1, 1),
'Rule': {
'Probabilistic': {
'DesiredSamplingPercentage': 123.0,
'ActualSamplingPercentage': 123.0
}
}
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
IndexingRules (list) --
Retrieves all indexing rules.
(dict) --
Rule used to determine the server-side sampling rate for spans ingested through the CloudWatchLogs destination and indexed by X-Ray.
Name (string) --
The name of the indexing rule.
ModifiedAt (datetime) --
Displays when the rule was last modified, in Unix time seconds.
Rule (dict) --
The indexing rule.
Probabilistic (dict) --
Indexing rule configuration that is used to probabilistically sample traceIds.
DesiredSamplingPercentage (float) --
Configured sampling percentage of traceIds. Note that sampling can be subject to limits to ensure completeness of data.
ActualSamplingPercentage (float) --
Applied sampling percentage of traceIds.
NextToken (string) --
Specify the pagination token returned by a previous request to retrieve the next page of indexes.
Retrieves a service graph for traces based on the specified RetrievalToken from the CloudWatch log group generated by Transaction Search. This API does not initiate a retrieval job. You must first execute StartTraceRetrieval to obtain the required RetrievalToken.
The trace graph describes services that process incoming requests and any downstream services they call, which may include Amazon Web Services resources, external APIs, or databases.
The response is empty until the RetrievalStatus is COMPLETE. Retry the request after the status changes from RUNNING or SCHEDULED to COMPLETE to access the full service graph.
When CloudWatch log is the destination, this API can support cross-account observability and service graph retrieval across linked accounts.
For retrieving graphs from X-Ray directly as opposed to the Transaction-Search Log group, see GetTraceGraph.
See also: AWS API Documentation
Request Syntax
client.get_retrieved_traces_graph(
RetrievalToken='string',
NextToken='string'
)
string
[REQUIRED]
Retrieval token.
string
Specify the pagination token returned by a previous request to retrieve the next page of indexes.
dict
Response Syntax
{
'RetrievalStatus': 'SCHEDULED'|'RUNNING'|'COMPLETE'|'FAILED'|'CANCELLED'|'TIMEOUT',
'Services': [
{
'Service': {
'ReferenceId': 123,
'Name': 'string',
'Names': [
'string',
],
'Root': True|False,
'AccountId': 'string',
'Type': 'string',
'State': 'string',
'StartTime': datetime(2015, 1, 1),
'EndTime': datetime(2015, 1, 1),
'Edges': [
{
'ReferenceId': 123,
'StartTime': datetime(2015, 1, 1),
'EndTime': datetime(2015, 1, 1),
'SummaryStatistics': {
'OkCount': 123,
'ErrorStatistics': {
'ThrottleCount': 123,
'OtherCount': 123,
'TotalCount': 123
},
'FaultStatistics': {
'OtherCount': 123,
'TotalCount': 123
},
'TotalCount': 123,
'TotalResponseTime': 123.0
},
'ResponseTimeHistogram': [
{
'Value': 123.0,
'Count': 123
},
],
'Aliases': [
{
'Name': 'string',
'Names': [
'string',
],
'Type': 'string'
},
],
'EdgeType': 'string',
'ReceivedEventAgeHistogram': [
{
'Value': 123.0,
'Count': 123
},
]
},
],
'SummaryStatistics': {
'OkCount': 123,
'ErrorStatistics': {
'ThrottleCount': 123,
'OtherCount': 123,
'TotalCount': 123
},
'FaultStatistics': {
'OtherCount': 123,
'TotalCount': 123
},
'TotalCount': 123,
'TotalResponseTime': 123.0
},
'DurationHistogram': [
{
'Value': 123.0,
'Count': 123
},
],
'ResponseTimeHistogram': [
{
'Value': 123.0,
'Count': 123
},
]
},
'Links': [
{
'ReferenceType': 'string',
'SourceTraceId': 'string',
'DestinationTraceIds': [
'string',
]
},
]
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
RetrievalStatus (string) --
Status of the retrieval.
Services (list) --
Retrieved services.
(dict) --
Retrieved information about an application that processed requests, users that made requests, or downstream services, resources, and applications that an application used.
Service (dict) --
Information about an application that processed requests, users that made requests, or downstream services, resources, and applications that an application used.
ReferenceId (integer) --
Identifier for the service. Unique within the service map.
Name (string) --
The canonical name of the service.
Names (list) --
A list of names for the service, including the canonical name.
(string) --
Root (boolean) --
Indicates that the service was the first service to process a request.
AccountId (string) --
Identifier of the Amazon Web Services account in which the service runs.
Type (string) --
The type of service.
Amazon Web Services Resource - The type of an Amazon Web Services resource. For example, AWS::EC2::Instance for an application running on Amazon EC2 or AWS::DynamoDB::Table for an Amazon DynamoDB table that the application used.
Amazon Web Services Service - The type of an Amazon Web Services service. For example, AWS::DynamoDB for downstream calls to Amazon DynamoDB that didn't target a specific table.
client - Represents the clients that sent requests to a root service.
remote - A downstream service of indeterminate type.
State (string) --
The service's state.
StartTime (datetime) --
The start time of the first segment that the service generated.
EndTime (datetime) --
The end time of the last segment that the service generated.
Edges (list) --
Connections to downstream services.
(dict) --
Information about a connection between two services. An edge can be a synchronous connection, such as typical call between client and service, or an asynchronous link, such as a Lambda function which retrieves an event from an SNS queue.
ReferenceId (integer) --
Identifier of the edge. Unique within a service map.
StartTime (datetime) --
The start time of the first segment on the edge.
EndTime (datetime) --
The end time of the last segment on the edge.
SummaryStatistics (dict) --
Response statistics for segments on the edge.
OkCount (integer) --
The number of requests that completed with a 2xx Success status code.
ErrorStatistics (dict) --
Information about requests that failed with a 4xx Client Error status code.
ThrottleCount (integer) --
The number of requests that failed with a 429 throttling status code.
OtherCount (integer) --
The number of requests that failed with untracked 4xx Client Error status codes.
TotalCount (integer) --
The total number of requests that failed with a 4xx Client Error status code.
FaultStatistics (dict) --
Information about requests that failed with a 5xx Server Error status code.
OtherCount (integer) --
The number of requests that failed with untracked 5xx Server Error status codes.
TotalCount (integer) --
The total number of requests that failed with a 5xx Server Error status code.
TotalCount (integer) --
The total number of completed requests.
TotalResponseTime (float) --
The aggregate response time of completed requests.
ResponseTimeHistogram (list) --
A histogram that maps the spread of client response times on an edge. Only populated for synchronous edges.
(dict) --
An entry in a histogram for a statistic. A histogram maps the range of observed values on the X axis, and the prevalence of each value on the Y axis.
Value (float) --
The value of the entry.
Count (integer) --
The prevalence of the entry.
Aliases (list) --
Aliases for the edge.
(dict) --
An alias for an edge.
Name (string) --
The canonical name of the alias.
Names (list) --
A list of names for the alias, including the canonical name.
(string) --
Type (string) --
The type of the alias.
EdgeType (string) --
Describes an asynchronous connection, with a value of link.
ReceivedEventAgeHistogram (list) --
A histogram that maps the spread of event age when received by consumers. Age is calculated each time an event is received. Only populated when EdgeType is link.
(dict) --
An entry in a histogram for a statistic. A histogram maps the range of observed values on the X axis, and the prevalence of each value on the Y axis.
Value (float) --
The value of the entry.
Count (integer) --
The prevalence of the entry.
SummaryStatistics (dict) --
Aggregated statistics for the service.
OkCount (integer) --
The number of requests that completed with a 2xx Success status code.
ErrorStatistics (dict) --
Information about requests that failed with a 4xx Client Error status code.
ThrottleCount (integer) --
The number of requests that failed with a 429 throttling status code.
OtherCount (integer) --
The number of requests that failed with untracked 4xx Client Error status codes.
TotalCount (integer) --
The total number of requests that failed with a 4xx Client Error status code.
FaultStatistics (dict) --
Information about requests that failed with a 5xx Server Error status code.
OtherCount (integer) --
The number of requests that failed with untracked 5xx Server Error status codes.
TotalCount (integer) --
The total number of requests that failed with a 5xx Server Error status code.
TotalCount (integer) --
The total number of completed requests.
TotalResponseTime (float) --
The aggregate response time of completed requests.
DurationHistogram (list) --
A histogram that maps the spread of service durations.
(dict) --
An entry in a histogram for a statistic. A histogram maps the range of observed values on the X axis, and the prevalence of each value on the Y axis.
Value (float) --
The value of the entry.
Count (integer) --
The prevalence of the entry.
ResponseTimeHistogram (list) --
A histogram that maps the spread of service response times.
(dict) --
An entry in a histogram for a statistic. A histogram maps the range of observed values on the X axis, and the prevalence of each value on the Y axis.
Value (float) --
The value of the entry.
Count (integer) --
The prevalence of the entry.
Links (list) --
Relation between two 2 services.
(dict) --
The relation between two services.
ReferenceType (string) --
Relationship of a trace to the corresponding service.
SourceTraceId (string) --
Source trace of a link relationship.
DestinationTraceIds (list) --
Destination traces of a link relationship.
(string) --
NextToken (string) --
Specify the pagination token returned by a previous request to retrieve the next page of indexes.
Retrieves a list of traces for a given RetrievalToken from the CloudWatch log group generated by Transaction Search. For information on what each trace returns, see BatchGetTraces.
This API does not initiate a retrieval job. To start a trace retrieval, use StartTraceRetrieval, which generates the required RetrievalToken.
When the RetrievalStatus is not COMPLETE, the API will return an empty response. Retry the request once the retrieval has completed to access the full list of traces.
For cross-account observability, this API can retrieve traces from linked accounts when CloudWatch log is the destination across relevant accounts. For more details, see CloudWatch cross-account observability.
For retrieving data from X-Ray directly as opposed to the Transaction-Search Log group, see BatchGetTraces.
See also: AWS API Documentation
Request Syntax
client.list_retrieved_traces(
RetrievalToken='string',
TraceFormat='XRAY'|'OTEL',
NextToken='string'
)
string
[REQUIRED]
Retrieval token.
string
Format of the requested traces.
string
Specify the pagination token returned by a previous request to retrieve the next page of indexes.
dict
Response Syntax
{
'RetrievalStatus': 'SCHEDULED'|'RUNNING'|'COMPLETE'|'FAILED'|'CANCELLED'|'TIMEOUT',
'TraceFormat': 'XRAY'|'OTEL',
'Traces': [
{
'Id': 'string',
'Duration': 123.0,
'Spans': [
{
'Id': 'string',
'Document': 'string'
},
]
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
RetrievalStatus (string) --
Status of the retrieval.
TraceFormat (string) --
Format of the requested traces.
Traces (list) --
Full traces for the specified requests.
(dict) --
Retrieved collection of spans with matching trace IDs.
Id (string) --
The unique identifier for the span.
Duration (float) --
The length of time in seconds between the start time of the root span and the end time of the last span that completed.
Spans (list) --
Spans that comprise the trace.
(dict) --
A span from a trace that has been ingested by the X-Ray service. A span represents a unit of work or an operation performed by a service.
Id (string) --
The span ID.
Document (string) --
The span document.
NextToken (string) --
Specify the pagination token returned by a previous request to retrieve the next page of indexes.
Cancels an ongoing trace retrieval job initiated by StartTraceRetrieval using the provided RetrievalToken. A successful cancellation will return an HTTP 200 response.
See also: AWS API Documentation
Request Syntax
client.cancel_trace_retrieval(
RetrievalToken='string'
)
string
[REQUIRED]
Retrieval token.
dict
Response Syntax
{}
Response Structure
(dict) --
Modifies the destination of data sent to PutTraceSegments. The Transaction Search feature requires the CloudWatchLogs destination. For more information, see Transaction Search.
See also: AWS API Documentation
Request Syntax
client.update_trace_segment_destination(
Destination='XRay'|'CloudWatchLogs'
)
string
The configured destination of trace segments.
dict
Response Syntax
{
'Destination': 'XRay'|'CloudWatchLogs',
'Status': 'PENDING'|'ACTIVE'
}
Response Structure
(dict) --
Destination (string) --
The destination of the trace segments.
Status (string) --
The status of the update.
Modifies an indexing rule’s configuration.
Indexing rules are used for determining the sampling rate for spans indexed from CloudWatch Logs. For more information, see Transaction Search.
See also: AWS API Documentation
Request Syntax
client.update_indexing_rule(
Name='string',
Rule={
'Probabilistic': {
'DesiredSamplingPercentage': 123.0
}
}
)
string
[REQUIRED]
Name of the indexing rule to be updated.
dict
[REQUIRED]
Rule configuration to be updated.
Probabilistic (dict) --
Indexing rule configuration that is used to probabilistically sample traceIds.
DesiredSamplingPercentage (float) -- [REQUIRED]
Configured sampling percentage of traceIds. Note that sampling can be subject to limits to ensure completeness of data.
dict
Response Syntax
{
'IndexingRule': {
'Name': 'string',
'ModifiedAt': datetime(2015, 1, 1),
'Rule': {
'Probabilistic': {
'DesiredSamplingPercentage': 123.0,
'ActualSamplingPercentage': 123.0
}
}
}
}
Response Structure
(dict) --
IndexingRule (dict) --
Updated indexing rule.
Name (string) --
The name of the indexing rule.
ModifiedAt (datetime) --
Displays when the rule was last modified, in Unix time seconds.
Rule (dict) --
The indexing rule.
Probabilistic (dict) --
Indexing rule configuration that is used to probabilistically sample traceIds.
DesiredSamplingPercentage (float) --
Configured sampling percentage of traceIds. Note that sampling can be subject to limits to ensure completeness of data.
ActualSamplingPercentage (float) --
Applied sampling percentage of traceIds.
Retrieves the current destination of data sent to PutTraceSegments and OpenTelemetry API. The Transaction Search feature requires a CloudWatchLogs destination. For more information, see Transaction Search and OpenTelemetry.
See also: AWS API Documentation
Request Syntax
client.get_trace_segment_destination()
dict
Response Syntax
{
'Destination': 'XRay'|'CloudWatchLogs',
'Status': 'PENDING'|'ACTIVE'
}
Response Structure
(dict) --
Destination (string) --
Retrieves the current destination.
Status (string) --
Status of the retrieval.
Initiates a trace retrieval process using the specified time range and for the give trace IDs on Transaction Search generated by the CloudWatch log group. For more information, see Transaction Search.
API returns a RetrievalToken, which can be used with ListRetrievedTraces or GetRetrievedTracesGraph to fetch results. Retrievals will time out after 60 minutes. To execute long time ranges, consider segmenting into multiple retrievals.
If you are using CloudWatch cross-account observability, you can use this operation in a monitoring account to retrieve data from a linked source account, as long as both accounts have transaction search enabled.
For retrieving data from X-Ray directly as opposed to the Transaction-Search Log group, see BatchGetTraces.
See also: AWS API Documentation
Request Syntax
client.start_trace_retrieval(
TraceIds=[
'string',
],
StartTime=datetime(2015, 1, 1),
EndTime=datetime(2015, 1, 1)
)
list
[REQUIRED]
Specify the trace IDs of the traces to be retrieved.
(string) --
datetime
[REQUIRED]
The start of the time range to retrieve traces. The range is inclusive, so the specified start time is included in the query. Specified as epoch time, the number of seconds since January 1, 1970, 00:00:00 UTC.
datetime
[REQUIRED]
The end of the time range to retrieve traces. The range is inclusive, so the specified end time is included in the query. Specified as epoch time, the number of seconds since January 1, 1970, 00:00:00 UTC.
dict
Response Syntax
{
'RetrievalToken': 'string'
}
Response Structure
(dict) --
RetrievalToken (string) --
Retrieval token.