Skip to content
AWS for Query.Farm

aws.xray.get_trace_summaries

Example SQL Queries

SELECT * FROM
aws.xray.get_trace_summaries
WHERE
"start_time" = 'VALUE'
AND "end_time" = 'VALUE';

Description

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 Using Filter Expressions in the Amazon Web Services X-Ray Developer Guide.

Table Definition

Column NameColumn Data Type
end_time Required Input Column

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

TIMESTAMP_S
start_time Required Input Column

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

TIMESTAMP_S
filter_expression Input Column

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

VARCHAR
sampling Input Column

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

BOOLEAN
sampling_strategy Input Column

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

STRUCT(
    "name" VARCHAR,
    "value" DOUBLE
)
Show child fields
sampling_strategy.name

The name of a sampling rule.

sampling_strategy.value

The value of a sampling rule.

time_range_type Input Column

A parameter to indicate whether to query trace summaries by TraceId, Event (trace update time), or Service (segment end time).

VARCHAR
_aws_profile Input Column

The AWS profile defines the AWS identity used. It can be defined via credentials or by assuming a IAM role.

STRUCT(
    "type" VARCHAR,
    "name" VARCHAR,
    "account_id" VARCHAR,
    "via_profile_name" VARCHAR,
    "assumed_role_arn" VARCHAR,
    "organization" STRUCT(
        "account_name" VARCHAR,
        "id" VARCHAR,
        "tags" STRUCT(
            "key" VARCHAR,
            "value" VARCHAR
        )[],
        "master_account" STRUCT(
            "id" VARCHAR,
            "email" VARCHAR
        ),
        "parents" STRUCT(
            "type" VARCHAR,
            "id" VARCHAR,
            "name" VARCHAR,
            "tags" STRUCT(
                "key" VARCHAR,
                "value" VARCHAR
            )[]
        )[]
    )
)
Show child fields
_aws_profile.account_id

The AWS account id

_aws_profile.assumed_role_arn

The ARN of the assumed role

_aws_profile.name

The unique name of the profile.

_aws_profile.organization

Information about this profile's membership in the AWS organization.

Show child fields
_aws_profile.organization.account_name

The name of account speciifed by the organization

_aws_profile.organization.id

The organization id

_aws_profile.organization.master_account
Show child fields
_aws_profile.organization.master_account.email

The organization master account email address

_aws_profile.organization.master_account.id

The organization master account id

_aws_profile.organization.parents[]
Show child fields
_aws_profile.organization.parents[].id

The id of the parent

_aws_profile.organization.parents[].name

The name of the parent

_aws_profile.organization.parents[].tags[]
Show child fields
_aws_profile.organization.parents[].tags[].key
_aws_profile.organization.parents[].tags[].value
_aws_profile.organization.parents[].type

The type of parent can be an organization unit or a root

_aws_profile.organization.tags[]
Show child fields
_aws_profile.organization.tags[].key
_aws_profile.organization.tags[].value
_aws_profile.type

The type of profile, either 'credentials' or 'assumed_role'

_aws_profile.via_profile_name

This IAM role for this profile is assumed by first utilizing another profile with this name to obtain credentials.

_aws_region Input Column

The AWS region to use.

VARCHAR
approximate_time

The start time of this page of results.

TIMESTAMP_S
trace_summaries

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

STRUCT(
    "id" VARCHAR,
    "start_time" TIMESTAMP_S,
    "duration" DOUBLE,
    "response_time" DOUBLE,
    "has_fault" BOOLEAN,
    "has_error" BOOLEAN,
    "has_throttle" BOOLEAN,
    "is_partial" BOOLEAN,
    "http" STRUCT(
        "http_url" VARCHAR,
        "http_status" BIGINT,
        "http_method" VARCHAR,
        "user_agent" VARCHAR,
        "client_ip" VARCHAR
    ),
    "annotations" MAP(VARCHAR, STRUCT(
            "annotation_value" STRUCT(
                "number_value" DOUBLE,
                "boolean_value" BOOLEAN,
                "string_value" VARCHAR
            ),
            "service_ids" STRUCT(
                "name" VARCHAR,
                "names" VARCHAR[],
                "account_id" VARCHAR,
                "type" VARCHAR
            )[]
        )[]),
    "users" STRUCT(
        "user_name" VARCHAR,
        "service_ids" STRUCT(
            "name" VARCHAR,
            "names" VARCHAR[],
            "account_id" VARCHAR,
            "type" VARCHAR
        )[]
    )[],
    "service_ids" STRUCT(
        "name" VARCHAR,
        "names" VARCHAR[],
        "account_id" VARCHAR,
        "type" VARCHAR
    )[],
    "resource_ar_ns" STRUCT(
        "arn" VARCHAR
    )[],
    "instance_ids" STRUCT(
        "id" VARCHAR
    )[],
    "availability_zones" STRUCT(
        "name" VARCHAR
    )[],
    "entry_point" STRUCT(
        "name" VARCHAR,
        "names" VARCHAR[],
        "account_id" VARCHAR,
        "type" VARCHAR
    ),
    "fault_root_causes" STRUCT(
        "services" STRUCT(
            "name" VARCHAR,
            "names" VARCHAR[],
            "type" VARCHAR,
            "account_id" VARCHAR,
            "entity_path" STRUCT(
                "name" VARCHAR,
                "exceptions" STRUCT(
                    "name" VARCHAR,
                    "message" VARCHAR
                )[],
                "remote" BOOLEAN
            )[],
            "inferred" BOOLEAN
        )[],
        "client_impacting" BOOLEAN
    )[],
    "error_root_causes" STRUCT(
        "services" STRUCT(
            "name" VARCHAR,
            "names" VARCHAR[],
            "type" VARCHAR,
            "account_id" VARCHAR,
            "entity_path" STRUCT(
                "name" VARCHAR,
                "exceptions" STRUCT(
                    "name" VARCHAR,
                    "message" VARCHAR
                )[],
                "remote" BOOLEAN
            )[],
            "inferred" BOOLEAN
        )[],
        "client_impacting" BOOLEAN
    )[],
    "response_time_root_causes" STRUCT(
        "services" STRUCT(
            "name" VARCHAR,
            "names" VARCHAR[],
            "type" VARCHAR,
            "account_id" VARCHAR,
            "entity_path" STRUCT(
                "name" VARCHAR,
                "coverage" DOUBLE,
                "remote" BOOLEAN
            )[],
            "inferred" BOOLEAN
        )[],
        "client_impacting" BOOLEAN
    )[],
    "revision" BIGINT,
    "matched_event_time" TIMESTAMP_S
)[]
Show child fields
trace_summaries[]
Show child fields
trace_summaries[].annotations

Annotations from the trace's segment documents.

trace_summaries[].availability_zones[]
Show child fields
trace_summaries[].availability_zones[].name

The name of a corresponding Availability Zone.

trace_summaries[].duration

The length of time in seconds between the start time of the root segment and the end time of the last segment that completed.

trace_summaries[].entry_point

The root of a trace.

Show child fields
trace_summaries[].entry_point.account_id

trace_summaries[].entry_point.name

trace_summaries[].entry_point.names[]
trace_summaries[].entry_point.type

trace_summaries[].error_root_causes[]
Show child fields
trace_summaries[].error_root_causes[].client_impacting

A flag that denotes that the root cause impacts the trace client.

trace_summaries[].error_root_causes[].services[]
Show child fields
trace_summaries[].error_root_causes[].services[].account_id

The account ID associated to the service.

trace_summaries[].error_root_causes[].services[].entity_path[]
Show child fields
trace_summaries[].error_root_causes[].services[].entity_path[].exceptions[]
Show child fields
trace_summaries[].error_root_causes[].services[].entity_path[].exceptions[].message

The message of the exception.

trace_summaries[].error_root_causes[].services[].entity_path[].exceptions[].name

The name of the exception.

trace_summaries[].error_root_causes[].services[].entity_path[].name

The name of the entity.

trace_summaries[].error_root_causes[].services[].entity_path[].remote

A flag that denotes a remote subsegment.

trace_summaries[].error_root_causes[].services[].inferred

A Boolean value indicating if the service is inferred from the trace.

trace_summaries[].error_root_causes[].services[].name

The service name.

trace_summaries[].error_root_causes[].services[].names[]
trace_summaries[].error_root_causes[].services[].type

The type associated to the service.

trace_summaries[].fault_root_causes[]
Show child fields
trace_summaries[].fault_root_causes[].client_impacting

A flag that denotes that the root cause impacts the trace client.

trace_summaries[].fault_root_causes[].services[]
Show child fields
trace_summaries[].fault_root_causes[].services[].account_id

The account ID associated to the service.

trace_summaries[].fault_root_causes[].services[].entity_path[]
Show child fields
trace_summaries[].fault_root_causes[].services[].entity_path[].exceptions[]
Show child fields
trace_summaries[].fault_root_causes[].services[].entity_path[].exceptions[].message

The message of the exception.

trace_summaries[].fault_root_causes[].services[].entity_path[].exceptions[].name

The name of the exception.

trace_summaries[].fault_root_causes[].services[].entity_path[].name

The name of the entity.

trace_summaries[].fault_root_causes[].services[].entity_path[].remote

A flag that denotes a remote subsegment.

trace_summaries[].fault_root_causes[].services[].inferred

A Boolean value indicating if the service is inferred from the trace.

trace_summaries[].fault_root_causes[].services[].name

The service name.

trace_summaries[].fault_root_causes[].services[].names[]
trace_summaries[].fault_root_causes[].services[].type

The type associated to the service.

trace_summaries[].has_error

The root segment document has a 400 series error.

trace_summaries[].has_fault

The root segment document has a 500 series error.

trace_summaries[].has_throttle

One or more of the segment documents has a 429 throttling error.

trace_summaries[].http

Information about the HTTP request served by the trace.

Show child fields
trace_summaries[].http.client_ip

The IP address of the requestor.

trace_summaries[].http.http_method

The request method.

trace_summaries[].http.http_status

The response status.

trace_summaries[].http.http_url

The request URL.

trace_summaries[].http.user_agent

The request's user agent string.

trace_summaries[].id

The unique identifier for the request that generated the trace's segments and subsegments.

trace_summaries[].instance_ids[]
Show child fields
trace_summaries[].instance_ids[].id

The ID of a corresponding EC2 instance.

trace_summaries[].is_partial

One or more of the segment documents is in progress.

trace_summaries[].matched_event_time

The matched time stamp of a defined event.

trace_summaries[].resource_ar_ns[]
Show child fields
trace_summaries[].resource_ar_ns[].arn

The ARN of a corresponding resource.

trace_summaries[].response_time

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.

trace_summaries[].response_time_root_causes[]
Show child fields
trace_summaries[].response_time_root_causes[].client_impacting

A flag that denotes that the root cause impacts the trace client.

trace_summaries[].response_time_root_causes[].services[]
Show child fields
trace_summaries[].response_time_root_causes[].services[].account_id

The account ID associated to the service.

trace_summaries[].response_time_root_causes[].services[].entity_path[]
Show child fields
trace_summaries[].response_time_root_causes[].services[].entity_path[].coverage

The type and messages of the exceptions.

trace_summaries[].response_time_root_causes[].services[].entity_path[].name

The name of the entity.

trace_summaries[].response_time_root_causes[].services[].entity_path[].remote

A flag that denotes a remote subsegment.

trace_summaries[].response_time_root_causes[].services[].inferred

A Boolean value indicating if the service is inferred from the trace.

trace_summaries[].response_time_root_causes[].services[].name

The service name.

trace_summaries[].response_time_root_causes[].services[].names[]
trace_summaries[].response_time_root_causes[].services[].type

The type associated to the service.

trace_summaries[].revision

The revision number of a trace.

trace_summaries[].service_ids[]
Show child fields
trace_summaries[].service_ids[].account_id

trace_summaries[].service_ids[].name

trace_summaries[].service_ids[].names[]
trace_summaries[].service_ids[].type

trace_summaries[].start_time

The start time of a trace, based on the earliest trace segment start time.

trace_summaries[].users[]
Show child fields
trace_summaries[].users[].service_ids[]
Show child fields
trace_summaries[].users[].service_ids[].account_id

trace_summaries[].users[].service_ids[].name

trace_summaries[].users[].service_ids[].names[]
trace_summaries[].users[].service_ids[].type

trace_summaries[].users[].user_name

The user's name.

traces_processed_count

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

BIGINT