Use the X-Ray API - AWS X-Ray

Use the X-Ray API

If the X-Ray SDK doesn’t support your programming language, you can use either the X-Ray APIs directly or the AWS Command Line Interface (AWS CLI) to call X-Ray API commands. Use the following guidance to choose how you interact with the API:

  • Use the AWS CLI for simpler syntax using pre-formatted commands or with options inside your request.

  • Use the X-Ray API directly for maximum flexibility and customization for requests that you make to X-Ray.

If you use the X-Ray API directly instead of the AWS CLI, you must parametrize your request in the correct data format and may also have to configure authentication and error handling.

The following diagram shows guidance to choose how to interact with the X-Ray API:

X-Ray displays detailed information about application requests.

Use the X-Ray API to send trace data to directly to X-Ray. The X-Ray API supports all functions available in the X-Ray SDK including the following common actions:

  • PutTraceSegments – Uploads segment documents to X-Ray.

  • BatchGetTraces – Retrieves a list of traces in a list of trace IDs. Each retrieved trace is a collection of segment documents from a single request.

  • GetTraceSummaries – Retrieves IDs and annotations for traces. You can specify a FilterExpression to retrieve a subset of trace summaries.

  • GetTraceGraph – Retrieves a service graph for a specific trace ID.

  • GetServiceGraph – Retrieves a JSON formatted document that describes services that process incoming requests and call downstream requests.

You can also use the AWS Command Line Interface (AWS CLI) inside your application code to programmatically interact with X-Ray. The AWS CLI supports all functions available in the X-Ray SDK including those for other AWS services. The following functions are versions of the API operations listed previously with a simpler format:

  • put-trace-segments – Uploads segment documents to X-Ray.

  • batch-get-traces – Retrieves a list of traces in a list of trace IDs. Each retrieved trace is a collection of segment documents from a single request.

  • get-trace-summaries – Retrieves IDs and annotations for traces. You can specify a FilterExpression to retrieve a subset of trace summaries.

  • get-trace-graph – Retrieves a service graph for a specific trace ID.

  • get-service-graph – Retrieves a JSON formatted document that describes services that process incoming requests and call downstream requests.

To get started, you must install the AWS CLI for your operating system. AWS supports Linux, macOS and Windows operating systems. For more information about the list of X-Ray commands, see the AWS CLI Command Reference guide for X-Ray.

Topics