2019/05/01 - AWS X-Ray - 1 new 1 updated api methods
Changes AWS X-Ray now includes Analytics, an interactive approach to analyzing user request paths (i.e., traces). Analytics will allow you to easily understand how your application and its underlying services are performing. With X-Ray Analytics, you can quickly detect application issues, pinpoint the root cause of the issue, determine the severity of the issues, and identify which end users were impacted. With AWS X-Ray Analytics you can explore, analyze, and visualize traces, allowing you to find increases in response time to user requests or increases in error rates. Metadata around peak periods, including frequency and actual times of occurrence, can be investigated by applying filters with a few clicks. You can then drill down on specific errors, faults, and response time root causes and view the associated traces.
Get an aggregation of service statistics defined by a specific time range.
See also: AWS API Documentation
Request Syntax
client.get_time_series_service_statistics(
StartTime=datetime(2015, 1, 1),
EndTime=datetime(2015, 1, 1),
GroupName='string',
GroupARN='string',
EntitySelectorExpression='string',
Period=123,
NextToken='string'
)
datetime
[REQUIRED]
The start of the time frame for which to aggregate statistics.
datetime
[REQUIRED]
The end of the time frame for which to aggregate statistics.
string
The case-sensitive name of the group for which to pull statistics from.
string
The ARN of the group for which to pull statistics from.
string
A filter expression defining entities that will be aggregated for statistics. Supports ID, service, and edge functions. If no selector expression is specified, edge statistics are returned.
integer
Aggregation period in seconds.
string
Pagination token. Not used.
dict
Response Syntax
{
'TimeSeriesServiceStatistics': [
{
'Timestamp': datetime(2015, 1, 1),
'EdgeSummaryStatistics': {
'OkCount': 123,
'ErrorStatistics': {
'ThrottleCount': 123,
'OtherCount': 123,
'TotalCount': 123
},
'FaultStatistics': {
'OtherCount': 123,
'TotalCount': 123
},
'TotalCount': 123,
'TotalResponseTime': 123.0
},
'ServiceSummaryStatistics': {
'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
},
]
},
],
'ContainsOldGroupVersions': True|False,
'NextToken': 'string'
}
Response Structure
(dict) --
TimeSeriesServiceStatistics (list) --
The collection of statistics.
(dict) --
A list of TimeSeriesStatistic structures.
Timestamp (datetime) --
Timestamp of the window for which statistics are aggregated.
EdgeSummaryStatistics (dict) --
Response statistics for an 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 419 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.
ServiceSummaryStatistics (dict) --
Response statistics for a 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 419 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) --
The response time histogram for the selected entities.
(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.
ContainsOldGroupVersions (boolean) --
A flag indicating whether or not a group's filter expression has been consistent, or if a returned aggregation may show statistics from an older version of the group's filter expression.
NextToken (string) --
Pagination token. Not used.
{'SamplingStrategy': {'Name': 'PartialScan | FixedRate', 'Value': 'double'},
'TimeRangeType': 'TraceId | Event'}
Response {'TraceSummaries': {'MatchedEventTime': 'timestamp'}}
Retrieves IDs and metadata for traces available for a specified time frame using an optional filter. To get the full traces, pass the trace IDs to BatchGetTraces .
A filter expression can target traced requests that hit specific service nodes or edges, have errors, or come from a known user. For example, the following filter expression targets traces that pass through api.example.com :
service("api.example.com")
This filter expression finds traces that have an annotation named account with the value 12345 :
annotation.account = "12345"
For a full list of indexed fields and keywords that you can use in filter expressions, see Using Filter Expressions in the AWS X-Ray Developer Guide .
See also: AWS API Documentation
Request Syntax
client.get_trace_summaries(
StartTime=datetime(2015, 1, 1),
EndTime=datetime(2015, 1, 1),
TimeRangeType='TraceId'|'Event',
Sampling=True|False,
SamplingStrategy={
'Name': 'PartialScan'|'FixedRate',
'Value': 123.0
},
FilterExpression='string',
NextToken='string'
)
datetime
[REQUIRED]
The start of the time frame for which to retrieve traces.
datetime
[REQUIRED]
The end of the time frame for which to retrieve traces.
string
A parameter to indicate whether to query trace summaries by TraceId or Event time.
boolean
Set to true to get summaries for only a subset of available traces.
dict
A paramater to indicate whether to enable sampling on trace summaries. Input parameters are Name and Value.
Name (string) --
The name of a sampling rule.
Value (float) --
The value of a sampling rule.
string
Specify a filter expression to retrieve trace summaries for services or requests that meet certain requirements.
string
Specify the pagination token returned by a previous request to retrieve the next page of results.
dict
Response Syntax
{
'TraceSummaries': [
{
'Id': 'string',
'Duration': 123.0,
'ResponseTime': 123.0,
'HasFault': True|False,
'HasError': True|False,
'HasThrottle': True|False,
'IsPartial': True|False,
'Http': {
'HttpURL': 'string',
'HttpStatus': 123,
'HttpMethod': 'string',
'UserAgent': 'string',
'ClientIp': 'string'
},
'Annotations': {
'string': [
{
'AnnotationValue': {
'NumberValue': 123.0,
'BooleanValue': True|False,
'StringValue': 'string'
},
'ServiceIds': [
{
'Name': 'string',
'Names': [
'string',
],
'AccountId': 'string',
'Type': 'string'
},
]
},
]
},
'Users': [
{
'UserName': 'string',
'ServiceIds': [
{
'Name': 'string',
'Names': [
'string',
],
'AccountId': 'string',
'Type': 'string'
},
]
},
],
'ServiceIds': [
{
'Name': 'string',
'Names': [
'string',
],
'AccountId': 'string',
'Type': 'string'
},
],
'ResourceARNs': [
{
'ARN': 'string'
},
],
'InstanceIds': [
{
'Id': 'string'
},
],
'AvailabilityZones': [
{
'Name': 'string'
},
],
'EntryPoint': {
'Name': 'string',
'Names': [
'string',
],
'AccountId': 'string',
'Type': 'string'
},
'FaultRootCauses': [
{
'Services': [
{
'Name': 'string',
'Names': [
'string',
],
'Type': 'string',
'AccountId': 'string',
'EntityPath': [
{
'Name': 'string',
'Exceptions': [
{
'Name': 'string',
'Message': 'string'
},
],
'Remote': True|False
},
],
'Inferred': True|False
},
]
},
],
'ErrorRootCauses': [
{
'Services': [
{
'Name': 'string',
'Names': [
'string',
],
'Type': 'string',
'AccountId': 'string',
'EntityPath': [
{
'Name': 'string',
'Exceptions': [
{
'Name': 'string',
'Message': 'string'
},
],
'Remote': True|False
},
],
'Inferred': True|False
},
]
},
],
'ResponseTimeRootCauses': [
{
'Services': [
{
'Name': 'string',
'Names': [
'string',
],
'Type': 'string',
'AccountId': 'string',
'EntityPath': [
{
'Name': 'string',
'Coverage': 123.0,
'Remote': True|False
},
],
'Inferred': True|False
},
]
},
],
'Revision': 123,
'MatchedEventTime': datetime(2015, 1, 1)
},
],
'ApproximateTime': datetime(2015, 1, 1),
'TracesProcessedCount': 123,
'NextToken': 'string'
}
Response Structure
(dict) --
TraceSummaries (list) --
Trace IDs and metadata for traces that were found in the specified time frame.
(dict) --
Metadata generated from the segment documents in a trace.
Id (string) --
The unique identifier for the request that generated the trace's segments and subsegments.
Duration (float) --
The length of time in seconds between the start time of the root segment and the end time of the last segment that completed.
ResponseTime (float) --
The length of time in seconds between the start and end times of the root segment. If the service performs work asynchronously, the response time measures the time before the response is sent to the user, while the duration measures the amount of time before the last traced activity completes.
HasFault (boolean) --
One or more of the segment documents has a 500 series error.
HasError (boolean) --
One or more of the segment documents has a 400 series error.
HasThrottle (boolean) --
One or more of the segment documents has a 429 throttling error.
IsPartial (boolean) --
One or more of the segment documents is in progress.
Http (dict) --
Information about the HTTP request served by the trace.
HttpURL (string) --
The request URL.
HttpStatus (integer) --
The response status.
HttpMethod (string) --
The request method.
UserAgent (string) --
The request's user agent string.
ClientIp (string) --
The IP address of the requestor.
Annotations (dict) --
Annotations from the trace's segment documents.
(string) --
(list) --
(dict) --
Information about a segment annotation.
AnnotationValue (dict) --
Values of the annotation.
NumberValue (float) --
Value for a Number annotation.
BooleanValue (boolean) --
Value for a Boolean annotation.
StringValue (string) --
Value for a String annotation.
ServiceIds (list) --
Services to which the annotation applies.
(dict) --
Name (string) --
Names (list) --
(string) --
AccountId (string) --
Type (string) --
Users (list) --
Users from the trace's segment documents.
(dict) --
Information about a user recorded in segment documents.
UserName (string) --
The user's name.
ServiceIds (list) --
Services that the user's request hit.
(dict) --
Name (string) --
Names (list) --
(string) --
AccountId (string) --
Type (string) --
ServiceIds (list) --
Service IDs from the trace's segment documents.
(dict) --
Name (string) --
Names (list) --
(string) --
AccountId (string) --
Type (string) --
ResourceARNs (list) --
A list of resource ARNs for any resource corresponding to the trace segments.
(dict) --
A list of resources ARNs corresponding to the segments in a trace.
ARN (string) --
The ARN of a corresponding resource.
InstanceIds (list) --
A list of EC2 instance IDs for any instance corresponding to the trace segments.
(dict) --
A list of EC2 instance IDs corresponding to the segments in a trace.
Id (string) --
The ID of a corresponding EC2 instance.
AvailabilityZones (list) --
A list of availability zones for any zone corresponding to the trace segments.
(dict) --
A list of availability zones corresponding to the segments in a trace.
Name (string) --
The name of a corresponding availability zone.
EntryPoint (dict) --
The root of a trace.
Name (string) --
Names (list) --
(string) --
AccountId (string) --
Type (string) --
FaultRootCauses (list) --
A collection of FaultRootCause structures corresponding to the the trace segments.
(dict) --
The root cause information for a trace summary fault.
Services (list) --
A list of corresponding services. A service identifies a segment and it contains a name, account ID, type, and inferred flag.
(dict) --
A collection of fields identifying the services in a trace summary fault.
Name (string) --
The service name.
Names (list) --
A collection of associated service names.
(string) --
Type (string) --
The type associated to the service.
AccountId (string) --
The account ID associated to the service.
EntityPath (list) --
The path of root cause entities found on the service.
(dict) --
A collection of segments and corresponding subsegments associated to a trace summary fault error.
Name (string) --
The name of the entity.
Exceptions (list) --
The types and messages of the exceptions.
(dict) --
The exception associated with a root cause.
Name (string) --
The name of the exception.
Message (string) --
The message of the exception.
Remote (boolean) --
A flag that denotes a remote subsegment.
Inferred (boolean) --
A Boolean value indicating if the service is inferred from the trace.
ErrorRootCauses (list) --
A collection of ErrorRootCause structures corresponding to the trace segments.
(dict) --
The root cause of a trace summary error.
Services (list) --
A list of services corresponding to an error. A service identifies a segment and it contains a name, account ID, type, and inferred flag.
(dict) --
A collection of fields identifying the services in a trace summary error.
Name (string) --
The service name.
Names (list) --
A collection of associated service names.
(string) --
Type (string) --
The type associated to the service.
AccountId (string) --
The account ID associated to the service.
EntityPath (list) --
The path of root cause entities found on the service.
(dict) --
A collection of segments and corresponding subsegments associated to a trace summary error.
Name (string) --
The name of the entity.
Exceptions (list) --
The types and messages of the exceptions.
(dict) --
The exception associated with a root cause.
Name (string) --
The name of the exception.
Message (string) --
The message of the exception.
Remote (boolean) --
A flag that denotes a remote subsegment.
Inferred (boolean) --
A Boolean value indicating if the service is inferred from the trace.
ResponseTimeRootCauses (list) --
A collection of ResponseTimeRootCause structures corresponding to the trace segments.
(dict) --
The root cause information for a response time warning.
Services (list) --
A list of corresponding services. A service identifies a segment and contains a name, account ID, type, and inferred flag.
(dict) --
A collection of fields identifying the service in a response time warning.
Name (string) --
The service name.
Names (list) --
A collection of associated service names.
(string) --
Type (string) --
The type associated to the service.
AccountId (string) --
The account ID associated to the service.
EntityPath (list) --
The path of root cause entities found on the service.
(dict) --
A collection of segments and corresponding subsegments associated to a response time warning.
Name (string) --
The name of the entity.
Coverage (float) --
The types and messages of the exceptions.
Remote (boolean) --
A flag that denotes a remote subsegment.
Inferred (boolean) --
A Boolean value indicating if the service is inferred from the trace.
Revision (integer) --
The revision number of a trace.
MatchedEventTime (datetime) --
The matched time stamp of a defined event.
ApproximateTime (datetime) --
The start time of this page of results.
TracesProcessedCount (integer) --
The total number of traces processed, including traces that did not match the specified filter expression.
NextToken (string) --
If the requested time frame contained more than one page of results, you can use this token to retrieve the next page. The first page contains the most most recent results, closest to the end of the time frame.