software.amazon.awssdk.services.xray

Interface XRayClient

All Superinterfaces:

AutoCloseable, SdkAutoCloseable, SdkClient

@Generated(value="software.amazon.awssdk:codegen")
public interface XRayClient
extends SdkClient, SdkAutoCloseable

Service client for accessing null. This can be created using the static builder() method.

AWS X-Ray provides APIs for managing debug traces and retrieving service maps and other data created by processing those traces.

Field Summary

Fields

Modifier and Type	Field and Description
static String	SERVICE_NAME

Method Summary

Modifier and Type	Method and Description
default BatchGetTracesResponse	batchGetTraces(BatchGetTracesRequest batchGetTracesRequest) Retrieves a list of traces specified by ID.
default BatchGetTracesResponse	batchGetTraces(Consumer<BatchGetTracesRequest.Builder> batchGetTracesRequest) Retrieves a list of traces specified by ID.
static XRayClientBuilder	builder() Create a builder that can be used to configure and create a XRayClient.
static XRayClient	create() Create a XRayClient with the region loaded from the DefaultAwsRegionProviderChain and credentials loaded from the DefaultCredentialsProvider.
default GetServiceGraphResponse	getServiceGraph(Consumer<GetServiceGraphRequest.Builder> getServiceGraphRequest) Retrieves a document that describes services that process incoming requests, and downstream services that they call as a result.
default GetServiceGraphResponse	getServiceGraph(GetServiceGraphRequest getServiceGraphRequest) Retrieves a document that describes services that process incoming requests, and downstream services that they call as a result.
default GetTraceGraphResponse	getTraceGraph(Consumer<GetTraceGraphRequest.Builder> getTraceGraphRequest) Retrieves a service graph for one or more specific trace IDs.
default GetTraceGraphResponse	getTraceGraph(GetTraceGraphRequest getTraceGraphRequest) Retrieves a service graph for one or more specific trace IDs.
default GetTraceSummariesResponse	getTraceSummaries(Consumer<GetTraceSummariesRequest.Builder> getTraceSummariesRequest) Retrieves IDs and metadata for traces available for a specified time frame using an optional filter.
default GetTraceSummariesResponse	getTraceSummaries(GetTraceSummariesRequest getTraceSummariesRequest) Retrieves IDs and metadata for traces available for a specified time frame using an optional filter.
default PutTelemetryRecordsResponse	putTelemetryRecords(Consumer<PutTelemetryRecordsRequest.Builder> putTelemetryRecordsRequest) Used by the AWS X-Ray daemon to upload telemetry.
default PutTelemetryRecordsResponse	putTelemetryRecords(PutTelemetryRecordsRequest putTelemetryRecordsRequest) Used by the AWS X-Ray daemon to upload telemetry.
default PutTraceSegmentsResponse	putTraceSegments(Consumer<PutTraceSegmentsRequest.Builder> putTraceSegmentsRequest) Uploads segment documents to AWS X-Ray.
default PutTraceSegmentsResponse	putTraceSegments(PutTraceSegmentsRequest putTraceSegmentsRequest) Uploads segment documents to AWS X-Ray.
static ServiceMetadata	serviceMetadata()

Methods inherited from interface software.amazon.awssdk.core.SdkClient

serviceName

Methods inherited from interface software.amazon.awssdk.utils.SdkAutoCloseable

close

Field Detail

SERVICE_NAME

static final String SERVICE_NAME

See Also:

Constant Field Values

Method Detail

create

static XRayClient create()

Create a XRayClient with the region loaded from the DefaultAwsRegionProviderChain and credentials loaded from the DefaultCredentialsProvider.

builder

static XRayClientBuilder builder()

Create a builder that can be used to configure and create a XRayClient.

batchGetTraces

default BatchGetTracesResponse batchGetTraces(BatchGetTracesRequest batchGetTracesRequest)
                                       throws InvalidRequestException,
                                              ThrottledException,
                                              AwsServiceException,
                                              SdkClientException,
                                              XRayException

Retrieves a list of traces specified by ID. Each trace is a collection of segment documents that originates from a single request. Use GetTraceSummaries to get a list of trace IDs.

Parameters:

batchGetTracesRequest -

Returns:

Result of the BatchGetTraces operation returned by the service.

Throws:

InvalidRequestException - The request is missing required parameters or has invalid parameters.

ThrottledException - The request exceeds the maximum number of requests per second.

SdkException - Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.

SdkClientException - If any client side error occurs such as an IO related failure, failure to get credentials, etc.

XRayException - Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.

AwsServiceException

See Also:

AWS API Documentation

batchGetTraces

default BatchGetTracesResponse batchGetTraces(Consumer<BatchGetTracesRequest.Builder> batchGetTracesRequest)
                                       throws InvalidRequestException,
                                              ThrottledException,
                                              AwsServiceException,
                                              SdkClientException,
                                              XRayException

Retrieves a list of traces specified by ID. Each trace is a collection of segment documents that originates from a single request. Use GetTraceSummaries to get a list of trace IDs.

This is a convenience which creates an instance of the BatchGetTracesRequest.Builder avoiding the need to create one manually via BatchGetTracesRequest.builder()

Parameters:

batchGetTracesRequest - A Consumer that will call methods on BatchGetTracesRequest.Builder to create a request.

Returns:

Result of the BatchGetTraces operation returned by the service.

Throws:

InvalidRequestException - The request is missing required parameters or has invalid parameters.

ThrottledException - The request exceeds the maximum number of requests per second.

SdkException - Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.

SdkClientException - If any client side error occurs such as an IO related failure, failure to get credentials, etc.

XRayException - Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.

AwsServiceException

See Also:

AWS API Documentation

getServiceGraph

default GetServiceGraphResponse getServiceGraph(GetServiceGraphRequest getServiceGraphRequest)
                                         throws InvalidRequestException,
                                                ThrottledException,
                                                AwsServiceException,
                                                SdkClientException,
                                                XRayException

Retrieves a document that describes services that process incoming requests, and downstream services that they call as a result. Root services process incoming requests and make calls to downstream services. Root services are applications that use the AWS X-Ray SDK. Downstream services can be other applications, AWS resources, HTTP web APIs, or SQL databases.

Parameters:

getServiceGraphRequest -

Returns:

Result of the GetServiceGraph operation returned by the service.

Throws:

InvalidRequestException - The request is missing required parameters or has invalid parameters.

ThrottledException - The request exceeds the maximum number of requests per second.

SdkException - Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.

SdkClientException - If any client side error occurs such as an IO related failure, failure to get credentials, etc.

XRayException - Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.

AwsServiceException

See Also:

AWS API Documentation

getServiceGraph

default GetServiceGraphResponse getServiceGraph(Consumer<GetServiceGraphRequest.Builder> getServiceGraphRequest)
                                         throws InvalidRequestException,
                                                ThrottledException,
                                                AwsServiceException,
                                                SdkClientException,
                                                XRayException

Retrieves a document that describes services that process incoming requests, and downstream services that they call as a result. Root services process incoming requests and make calls to downstream services. Root services are applications that use the AWS X-Ray SDK. Downstream services can be other applications, AWS resources, HTTP web APIs, or SQL databases.

This is a convenience which creates an instance of the GetServiceGraphRequest.Builder avoiding the need to create one manually via GetServiceGraphRequest.builder()

Parameters:

getServiceGraphRequest - A Consumer that will call methods on GetServiceGraphRequest.Builder to create a request.

Returns:

Result of the GetServiceGraph operation returned by the service.

Throws:

InvalidRequestException - The request is missing required parameters or has invalid parameters.

ThrottledException - The request exceeds the maximum number of requests per second.

SdkException - Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.

SdkClientException - If any client side error occurs such as an IO related failure, failure to get credentials, etc.

XRayException - Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.

AwsServiceException

See Also:

AWS API Documentation

getTraceGraph

default GetTraceGraphResponse getTraceGraph(GetTraceGraphRequest getTraceGraphRequest)
                                     throws InvalidRequestException,
                                            ThrottledException,
                                            AwsServiceException,
                                            SdkClientException,
                                            XRayException

Retrieves a service graph for one or more specific trace IDs.

Parameters:

getTraceGraphRequest -

Returns:

Result of the GetTraceGraph operation returned by the service.

Throws:

InvalidRequestException - The request is missing required parameters or has invalid parameters.

ThrottledException - The request exceeds the maximum number of requests per second.

SdkException - Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.

SdkClientException - If any client side error occurs such as an IO related failure, failure to get credentials, etc.

XRayException - Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.

AwsServiceException

See Also:

AWS API Documentation

getTraceGraph

default GetTraceGraphResponse getTraceGraph(Consumer<GetTraceGraphRequest.Builder> getTraceGraphRequest)
                                     throws InvalidRequestException,
                                            ThrottledException,
                                            AwsServiceException,
                                            SdkClientException,
                                            XRayException

Retrieves a service graph for one or more specific trace IDs.

This is a convenience which creates an instance of the GetTraceGraphRequest.Builder avoiding the need to create one manually via GetTraceGraphRequest.builder()

Parameters:

getTraceGraphRequest - A Consumer that will call methods on GetTraceGraphRequest.Builder to create a request.

Returns:

Result of the GetTraceGraph operation returned by the service.

Throws:

InvalidRequestException - The request is missing required parameters or has invalid parameters.

ThrottledException - The request exceeds the maximum number of requests per second.

SdkException - Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.

SdkClientException - If any client side error occurs such as an IO related failure, failure to get credentials, etc.

XRayException - Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.

AwsServiceException

See Also:

AWS API Documentation

getTraceSummaries

default GetTraceSummariesResponse getTraceSummaries(GetTraceSummariesRequest getTraceSummariesRequest)
                                             throws InvalidRequestException,
                                                    ThrottledException,
                                                    AwsServiceException,
                                                    SdkClientException,
                                                    XRayException

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.

Parameters:

getTraceSummariesRequest -

Returns:

Result of the GetTraceSummaries operation returned by the service.

Throws:

InvalidRequestException - The request is missing required parameters or has invalid parameters.

ThrottledException - The request exceeds the maximum number of requests per second.

SdkException - Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.

SdkClientException - If any client side error occurs such as an IO related failure, failure to get credentials, etc.

XRayException - Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.

AwsServiceException

See Also:

AWS API Documentation

getTraceSummaries

default GetTraceSummariesResponse getTraceSummaries(Consumer<GetTraceSummariesRequest.Builder> getTraceSummariesRequest)
                                             throws InvalidRequestException,
                                                    ThrottledException,
                                                    AwsServiceException,
                                                    SdkClientException,
                                                    XRayException

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.

This is a convenience which creates an instance of the GetTraceSummariesRequest.Builder avoiding the need to create one manually via GetTraceSummariesRequest.builder()

Parameters:

getTraceSummariesRequest - A Consumer that will call methods on GetTraceSummariesRequest.Builder to create a request.

Returns:

Result of the GetTraceSummaries operation returned by the service.

Throws:

InvalidRequestException - The request is missing required parameters or has invalid parameters.

ThrottledException - The request exceeds the maximum number of requests per second.

SdkException - Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.

SdkClientException - If any client side error occurs such as an IO related failure, failure to get credentials, etc.

XRayException - Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.

AwsServiceException

See Also:

AWS API Documentation

putTelemetryRecords

default PutTelemetryRecordsResponse putTelemetryRecords(PutTelemetryRecordsRequest putTelemetryRecordsRequest)
                                                 throws InvalidRequestException,
                                                        ThrottledException,
                                                        AwsServiceException,
                                                        SdkClientException,
                                                        XRayException

Used by the AWS X-Ray daemon to upload telemetry.

Parameters:

putTelemetryRecordsRequest -

Returns:

Result of the PutTelemetryRecords operation returned by the service.

Throws:

InvalidRequestException - The request is missing required parameters or has invalid parameters.

ThrottledException - The request exceeds the maximum number of requests per second.

SdkException - Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.

SdkClientException - If any client side error occurs such as an IO related failure, failure to get credentials, etc.

XRayException - Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.

AwsServiceException

See Also:

AWS API Documentation

putTelemetryRecords

default PutTelemetryRecordsResponse putTelemetryRecords(Consumer<PutTelemetryRecordsRequest.Builder> putTelemetryRecordsRequest)
                                                 throws InvalidRequestException,
                                                        ThrottledException,
                                                        AwsServiceException,
                                                        SdkClientException,
                                                        XRayException

Used by the AWS X-Ray daemon to upload telemetry.

This is a convenience which creates an instance of the PutTelemetryRecordsRequest.Builder avoiding the need to create one manually via PutTelemetryRecordsRequest.builder()

Parameters:

putTelemetryRecordsRequest - A Consumer that will call methods on PutTelemetryRecordsRequest.Builder to create a request.

Returns:

Result of the PutTelemetryRecords operation returned by the service.

Throws:

InvalidRequestException - The request is missing required parameters or has invalid parameters.

ThrottledException - The request exceeds the maximum number of requests per second.

SdkException - Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.

SdkClientException - If any client side error occurs such as an IO related failure, failure to get credentials, etc.

XRayException - Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.

AwsServiceException

See Also:

AWS API Documentation

putTraceSegments

default PutTraceSegmentsResponse putTraceSegments(PutTraceSegmentsRequest putTraceSegmentsRequest)
                                           throws InvalidRequestException,
                                                  ThrottledException,
                                                  AwsServiceException,
                                                  SdkClientException,
                                                  XRayException

Uploads segment documents to AWS X-Ray. The X-Ray SDK generates segment documents and sends them to the X-Ray daemon, which uploads them in batches. A segment document can be a completed segment, an in-progress segment, or an array of subsegments.

Segments must include the following fields. For the full segment document schema, see AWS X-Ray Segment Documents in the AWS X-Ray Developer Guide.

Required Segment Document Fields

• name - The name of the service that handled the request.

• id - A 64-bit identifier for the segment, unique among segments in the same trace, in 16 hexadecimal digits.

• trace_id - A unique identifier that connects all segments and subsegments originating from a single client request.

• start_time - Time the segment or subsegment was created, in floating point seconds in epoch time, accurate to milliseconds. For example, 1480615200.010 or 1.480615200010E9.

• end_time - Time the segment or subsegment was closed. For example, 1480615200.090 or 1.480615200090E9. Specify either an end_time or in_progress.

• in_progress - Set to true instead of specifying an end_time to record that a segment has been started, but is not complete. Send an in progress segment when your application receives a request that will take a long time to serve, to trace the fact that the request was received. When the response is sent, send the complete segment to overwrite the in-progress segment.

A trace_id consists of three numbers separated by hyphens. For example, 1-58406520-a006649127e371903a2de979. This includes:

Trace ID Format

• The version number, i.e. 1.

• The time of the original request, in Unix epoch time, in 8 hexadecimal digits. For example, 10:00AM December 2nd, 2016 PST in epoch time is 1480615200 seconds, or 58406520 in hexadecimal.

• A 96-bit identifier for the trace, globally unique, in 24 hexadecimal digits.

Parameters:

putTraceSegmentsRequest -

Returns:

Result of the PutTraceSegments operation returned by the service.

Throws:

InvalidRequestException - The request is missing required parameters or has invalid parameters.

ThrottledException - The request exceeds the maximum number of requests per second.

SdkException - Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.

SdkClientException - If any client side error occurs such as an IO related failure, failure to get credentials, etc.

XRayException - Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.

AwsServiceException

See Also:

AWS API Documentation

putTraceSegments

default PutTraceSegmentsResponse putTraceSegments(Consumer<PutTraceSegmentsRequest.Builder> putTraceSegmentsRequest)
                                           throws InvalidRequestException,
                                                  ThrottledException,
                                                  AwsServiceException,
                                                  SdkClientException,
                                                  XRayException

Uploads segment documents to AWS X-Ray. The X-Ray SDK generates segment documents and sends them to the X-Ray daemon, which uploads them in batches. A segment document can be a completed segment, an in-progress segment, or an array of subsegments.

Segments must include the following fields. For the full segment document schema, see AWS X-Ray Segment Documents in the AWS X-Ray Developer Guide.

Required Segment Document Fields

• name - The name of the service that handled the request.

• id - A 64-bit identifier for the segment, unique among segments in the same trace, in 16 hexadecimal digits.

• trace_id - A unique identifier that connects all segments and subsegments originating from a single client request.

• start_time - Time the segment or subsegment was created, in floating point seconds in epoch time, accurate to milliseconds. For example, 1480615200.010 or 1.480615200010E9.

• end_time - Time the segment or subsegment was closed. For example, 1480615200.090 or 1.480615200090E9. Specify either an end_time or in_progress.

• in_progress - Set to true instead of specifying an end_time to record that a segment has been started, but is not complete. Send an in progress segment when your application receives a request that will take a long time to serve, to trace the fact that the request was received. When the response is sent, send the complete segment to overwrite the in-progress segment.

A trace_id consists of three numbers separated by hyphens. For example, 1-58406520-a006649127e371903a2de979. This includes:

Trace ID Format

• The version number, i.e. 1.

• The time of the original request, in Unix epoch time, in 8 hexadecimal digits. For example, 10:00AM December 2nd, 2016 PST in epoch time is 1480615200 seconds, or 58406520 in hexadecimal.

• A 96-bit identifier for the trace, globally unique, in 24 hexadecimal digits.

This is a convenience which creates an instance of the PutTraceSegmentsRequest.Builder avoiding the need to create one manually via PutTraceSegmentsRequest.builder()

Parameters:

putTraceSegmentsRequest - A Consumer that will call methods on PutTraceSegmentsRequest.Builder to create a request.

Returns:

Result of the PutTraceSegments operation returned by the service.

Throws:

InvalidRequestException - The request is missing required parameters or has invalid parameters.

ThrottledException - The request exceeds the maximum number of requests per second.

SdkException - Base class for all exceptions that can be thrown by the SDK (both service and client). Can be used for catch all scenarios.

SdkClientException - If any client side error occurs such as an IO related failure, failure to get credentials, etc.

XRayException - Base class for all service exceptions. Unknown exceptions will be thrown as an instance of this type.

AwsServiceException

See Also:

AWS API Documentation

serviceMetadata

static ServiceMetadata serviceMetadata()