GetTraceSummariesCommand

Suggest an Edit

Retrieves IDs and annotations 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 Use filter expressions  in the Amazon Web Services X-Ray Developer Guide.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { XRayClient, GetTraceSummariesCommand } from "@aws-sdk/client-xray"; // ES Modules import
// const { XRayClient, GetTraceSummariesCommand } = require("@aws-sdk/client-xray"); // CommonJS import
const client = new XRayClient(config);
const input = { // GetTraceSummariesRequest
  StartTime: new Date("TIMESTAMP"), // required
  EndTime: new Date("TIMESTAMP"), // required
  TimeRangeType: "TraceId" || "Event" || "Service",
  Sampling: true || false,
  SamplingStrategy: { // SamplingStrategy
    Name: "PartialScan" || "FixedRate",
    Value: Number("double"),
  },
  FilterExpression: "STRING_VALUE",
  NextToken: "STRING_VALUE",
};
const command = new GetTraceSummariesCommand(input);
const response = await client.send(command);
// { // GetTraceSummariesResult
//   TraceSummaries: [ // TraceSummaryList
//     { // TraceSummary
//       Id: "STRING_VALUE",
//       StartTime: new Date("TIMESTAMP"),
//       Duration: Number("double"),
//       ResponseTime: Number("double"),
//       HasFault: true || false,
//       HasError: true || false,
//       HasThrottle: true || false,
//       IsPartial: true || false,
//       Http: { // Http
//         HttpURL: "STRING_VALUE",
//         HttpStatus: Number("int"),
//         HttpMethod: "STRING_VALUE",
//         UserAgent: "STRING_VALUE",
//         ClientIp: "STRING_VALUE",
//       },
//       Annotations: { // Annotations
//         "<keys>": [ // ValuesWithServiceIds
//           { // ValueWithServiceIds
//             AnnotationValue: { // AnnotationValue Union: only one key present
//               NumberValue: Number("double"),
//               BooleanValue: true || false,
//               StringValue: "STRING_VALUE",
//             },
//             ServiceIds: [ // ServiceIds
//               { // ServiceId
//                 Name: "STRING_VALUE",
//                 Names: [ // ServiceNames
//                   "STRING_VALUE",
//                 ],
//                 AccountId: "STRING_VALUE",
//                 Type: "STRING_VALUE",
//               },
//             ],
//           },
//         ],
//       },
//       Users: [ // TraceUsers
//         { // TraceUser
//           UserName: "STRING_VALUE",
//           ServiceIds: [
//             {
//               Name: "STRING_VALUE",
//               Names: [
//                 "STRING_VALUE",
//               ],
//               AccountId: "STRING_VALUE",
//               Type: "STRING_VALUE",
//             },
//           ],
//         },
//       ],
//       ServiceIds: "<ServiceIds>",
//       ResourceARNs: [ // TraceResourceARNs
//         { // ResourceARNDetail
//           ARN: "STRING_VALUE",
//         },
//       ],
//       InstanceIds: [ // TraceInstanceIds
//         { // InstanceIdDetail
//           Id: "STRING_VALUE",
//         },
//       ],
//       AvailabilityZones: [ // TraceAvailabilityZones
//         { // AvailabilityZoneDetail
//           Name: "STRING_VALUE",
//         },
//       ],
//       EntryPoint: "<ServiceId>",
//       FaultRootCauses: [ // FaultRootCauses
//         { // FaultRootCause
//           Services: [ // FaultRootCauseServices
//             { // FaultRootCauseService
//               Name: "STRING_VALUE",
//               Names: [
//                 "STRING_VALUE",
//               ],
//               Type: "STRING_VALUE",
//               AccountId: "STRING_VALUE",
//               EntityPath: [ // FaultRootCauseEntityPath
//                 { // FaultRootCauseEntity
//                   Name: "STRING_VALUE",
//                   Exceptions: [ // RootCauseExceptions
//                     { // RootCauseException
//                       Name: "STRING_VALUE",
//                       Message: "STRING_VALUE",
//                     },
//                   ],
//                   Remote: true || false,
//                 },
//               ],
//               Inferred: true || false,
//             },
//           ],
//           ClientImpacting: true || false,
//         },
//       ],
//       ErrorRootCauses: [ // ErrorRootCauses
//         { // ErrorRootCause
//           Services: [ // ErrorRootCauseServices
//             { // ErrorRootCauseService
//               Name: "STRING_VALUE",
//               Names: [
//                 "STRING_VALUE",
//               ],
//               Type: "STRING_VALUE",
//               AccountId: "STRING_VALUE",
//               EntityPath: [ // ErrorRootCauseEntityPath
//                 { // ErrorRootCauseEntity
//                   Name: "STRING_VALUE",
//                   Exceptions: [
//                     {
//                       Name: "STRING_VALUE",
//                       Message: "STRING_VALUE",
//                     },
//                   ],
//                   Remote: true || false,
//                 },
//               ],
//               Inferred: true || false,
//             },
//           ],
//           ClientImpacting: true || false,
//         },
//       ],
//       ResponseTimeRootCauses: [ // ResponseTimeRootCauses
//         { // ResponseTimeRootCause
//           Services: [ // ResponseTimeRootCauseServices
//             { // ResponseTimeRootCauseService
//               Name: "STRING_VALUE",
//               Names: [
//                 "STRING_VALUE",
//               ],
//               Type: "STRING_VALUE",
//               AccountId: "STRING_VALUE",
//               EntityPath: [ // ResponseTimeRootCauseEntityPath
//                 { // ResponseTimeRootCauseEntity
//                   Name: "STRING_VALUE",
//                   Coverage: Number("double"),
//                   Remote: true || false,
//                 },
//               ],
//               Inferred: true || false,
//             },
//           ],
//           ClientImpacting: true || false,
//         },
//       ],
//       Revision: Number("int"),
//       MatchedEventTime: new Date("TIMESTAMP"),
//     },
//   ],
//   ApproximateTime: new Date("TIMESTAMP"),
//   TracesProcessedCount: Number("long"),
//   NextToken: "STRING_VALUE",
// };

GetTraceSummariesCommand Input

See GetTraceSummariesCommandInput for more details

Parameter
Type
Description
EndTime
Required
Date | undefined

The end of the time frame for which to retrieve traces.

StartTime
Required
Date | undefined

The start of the time frame for which to retrieve traces.

FilterExpression
string | undefined

Specify a filter expression to retrieve trace summaries for services or requests that meet certain requirements.

NextToken
string | undefined

Specify the pagination token returned by a previous request to retrieve the next page of results.

Sampling
boolean | undefined

Set to true to get summaries for only a subset of available traces.

SamplingStrategy
SamplingStrategy | undefined

A parameter to indicate whether to enable sampling on trace summaries. Input parameters are Name and Value.

TimeRangeType
TimeRangeType | undefined

Query trace summaries by TraceId (trace start time), Event (trace update time), or Service (trace segment end time).

GetTraceSummariesCommand Output

See GetTraceSummariesCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
ApproximateTime
Date | undefined

The start time of this page of results.

NextToken
string | undefined

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 recent results, closest to the end of the time frame.

TraceSummaries
TraceSummary[] | undefined

Trace IDs and annotations for traces that were found in the specified time frame.

TracesProcessedCount
number | undefined

The total number of traces processed, including traces that did not match the specified filter expression.

Throws

Name
Fault
Details
InvalidRequestException
client

The request is missing required parameters or has invalid parameters.

ThrottledException
client

The request exceeds the maximum number of requests per second.

XRayServiceException
Base exception class for all service exceptions from XRay service.