Package software.amazon.awssdk.services.xray

Interface XRayClient

All Superinterfaces:

AutoCloseable

@Generated("software.amazon.awssdk:codegen")
public interface XRayClient
extends AutoCloseable

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	Description
static String	SERVICE_NAME

Method Summary

Modifier and Type	Method	Description
default BatchGetTracesResponse	batchGetTraces(BatchGetTracesRequest 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(GetServiceGraphRequest getServiceGraphRequest)	Retrieves a document that describes services that process incoming requests, and downstream services that they call as a result.
default GetTraceGraphResponse	getTraceGraph(GetTraceGraphRequest getTraceGraphRequest)	Retrieves a service graph for one or more specific trace IDs.
default GetTraceSummariesResponse	getTraceSummaries(GetTraceSummariesRequest getTraceSummariesRequest)	Retrieves IDs and metadata for traces available for a specified time frame using an optional filter.
default PutTelemetryRecordsResponse	putTelemetryRecords(PutTelemetryRecordsRequest putTelemetryRecordsRequest)	Used by the AWS X-Ray daemon to upload telemetry.
default PutTraceSegmentsResponse	putTraceSegments(PutTraceSegmentsRequest putTraceSegmentsRequest)	Uploads segment documents to AWS X-Ray.
static ServiceMetadata	serviceMetadata()

Methods inherited from interface java.lang.AutoCloseable

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,
                                              SdkBaseException,
                                              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.

SdkBaseException - 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 exception for all service exceptions. Unknown exceptions will be thrown as an instance of this type

See Also:

AWS API Documentation

getServiceGraph

default GetServiceGraphResponse getServiceGraph(GetServiceGraphRequest getServiceGraphRequest)
                                         throws InvalidRequestException,
                                                ThrottledException,
                                                SdkBaseException,
                                                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.

SdkBaseException - 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 exception for all service exceptions. Unknown exceptions will be thrown as an instance of this type

See Also:

AWS API Documentation

getTraceGraph

default GetTraceGraphResponse getTraceGraph(GetTraceGraphRequest getTraceGraphRequest)
                                     throws InvalidRequestException,
                                            ThrottledException,
                                            SdkBaseException,
                                            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.

SdkBaseException - 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 exception for all service exceptions. Unknown exceptions will be thrown as an instance of this type

See Also:

AWS API Documentation

getTraceSummaries

default GetTraceSummariesResponse getTraceSummaries(GetTraceSummariesRequest getTraceSummariesRequest)
                                             throws InvalidRequestException,
                                                    ThrottledException,
                                                    SdkBaseException,
                                                    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.

SdkBaseException - 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 exception for all service exceptions. Unknown exceptions will be thrown as an instance of this type

See Also:

AWS API Documentation

putTelemetryRecords

default PutTelemetryRecordsResponse putTelemetryRecords(PutTelemetryRecordsRequest putTelemetryRecordsRequest)
                                                 throws InvalidRequestException,
                                                        ThrottledException,
                                                        SdkBaseException,
                                                        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.

SdkBaseException - 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 exception for all service exceptions. Unknown exceptions will be thrown as an instance of this type

See Also:

AWS API Documentation

putTraceSegments

default PutTraceSegmentsResponse putTraceSegments(PutTraceSegmentsRequest putTraceSegmentsRequest)
                                           throws InvalidRequestException,
                                                  ThrottledException,
                                                  SdkBaseException,
                                                  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.

SdkBaseException - 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 exception for all service exceptions. Unknown exceptions will be thrown as an instance of this type

See Also:

AWS API Documentation

serviceMetadata

static ServiceMetadata serviceMetadata()