Use the X-Ray API - Amazon X-Ray
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

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 Amazon Command Line Interface (Amazon CLI) to call X-Ray API commands. Use the following guidance to choose how you interact with the API:

  • Use the Amazon 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 Amazon 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 Amazon Command Line Interface (Amazon CLI) inside your application code to programmatically interact with X-Ray. The Amazon CLI supports all functions available in the X-Ray SDK including those for other Amazon Web 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 Amazon CLI for your operating system. Amazon supports Linux, macOS and Windows operating systems. For more information about the list of X-Ray commands, see the Amazon CLI Command Reference guide for X-Ray.

Topics