# Trace user requests to REST APIs using X-Ray in API Gateway You can use [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) to trace and analyze user requests as they travel through your Amazon API Gateway REST APIs to the underlying services. API Gateway supports X-Ray tracing for all API Gateway REST API endpoint types: Regional, edge-optimized, and private. You can use X-Ray with Amazon API Gateway in all AWS Regions where X-Ray is available. Because X-Ray gives you an end-to-end view of an entire request, you can analyze latencies in your APIs and their backend services. You can use an X-Ray service map to view the latency of an entire request and that of the downstream services that are integrated with X-Ray. You can also configure sampling rules to tell X-Ray which requests to record and at what sampling rates, according to criteria that you specify. If you call an API Gateway API from a service that's already being traced, API Gateway passes the trace through, even if X-Ray tracing isn't enabled on the API. You can enable X-Ray for an API stage by using the API Gateway console, or by using the API Gateway API or CLI. **Topics** + [Set up AWS X-Ray with API Gateway REST APIs](apigateway-enabling-xray.md) + [Use AWS X-Ray service maps and trace views with API Gateway](apigateway-using-xray-maps.md) + [Configure AWS X-Ray sampling rules for API Gateway APIs](apigateway-configuring-xray-sampling-rules.md) + [AWS X-Ray traces for Amazon API Gateway APIs](apigateway-understanding-xray-traces.md) # Set up AWS X-Ray with API Gateway REST APIs In this section you can find detailed information on how to set up [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) with API Gateway REST APIs. **Topics** + [X-Ray tracing modes for API Gateway](#apigateway-tracing-modes) + [Permissions for X-Ray tracing](#set-up-xray-tracing-permissions) + [Enabling X-Ray tracing in the API Gateway console](#apigateway-xray-console-setup) + [Enabling AWS X-Ray tracing using the API Gateway CLI](#apigateway-xray-cli-setup) ## X-Ray tracing modes for API Gateway The path of a request through your application is tracked with a trace ID. A trace collects all of the segments generated by a single request, typically an HTTP `GET` or `POST` request. There are two modes of tracing for an API Gateway API: + **Passive**: This is the default setting if you have not enabled X-Ray tracing on an API stage. This approach means that the API Gateway API is only traced if X-Ray has been enabled on an upstream service. + **Active**: When an API Gateway API stage has this setting, API Gateway automatically samples API invocation requests, based on the sampling algorithm specified by X-Ray. When active tracing is enabled on a stage, API Gateway creates a service-linked role in your account, if the role does not exist already. The role is named `AWSServiceRoleForAPIGateway` and will have the `APIGatewayServiceRolePolicy` managed policy attached to it. For more information about service-linked roles, see [Using Service-Linked Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html). **Note** X-Ray applies a sampling algorithm to ensure that tracing is efficient, while still providing a representative sample of the requests that your API receives. The default sampling algorithm is 1 request per second, with 5 percent of requests sampled past that limit. You can change the tracing mode for your API by using the API Gateway management console, the API Gateway CLI, or an AWS SDK. ## Permissions for X-Ray tracing When you enable X-Ray tracing on a stage, API Gateway creates a service-linked role in your account, if the role does not exist already. The role is named `AWSServiceRoleForAPIGateway` and will have the `APIGatewayServiceRolePolicy` managed policy attached to it. For more information about service-linked roles, see [Using Service-Linked Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html). ## Enabling X-Ray tracing in the API Gateway console You can use the Amazon API Gateway console to enable active tracing on an API stage. These steps assume that you have already deployed the API to a stage. 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Choose your API, and then in the main navigation pane, choose **Stages**. 1. In the **Stages** pane, choose a stage. 1. In the **Logs and tracing** section, choose **Edit**. 1. To enable active X-Ray tracing, select **X-Ray tracing** to turn on X-Ray tracing. 1. Choose **Save changes**. Once you've enabled X-Ray for your API stage, you can use the X-Ray management console to view the traces and service maps. ## Enabling AWS X-Ray tracing using the API Gateway CLI The following [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) command creates a stage with active X-Ray tracing: ``` aws apigateway create-stage \ --rest-api-id rest-api-id \ --stage-name stage-name \ --deployment-id deployment-id \ --region region \ --tracing-enabled=true ``` The output will look like the following: ``` { "tracingEnabled": true, "stageName": stage-name, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": deployment-id, "lastUpdatedDate": 1533849811, "createdDate": 1533849811, "methodSettings": {} } ``` The following [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) command creates a stage without active X-Ray tracing: ``` aws apigateway create-stage \ --rest-api-id rest-api-id \ --stage-name stage-name \ --deployment-id deployment-id \ --region region \ --tracing-enabled=false ``` The output will look like the following: ``` { "tracingEnabled": false, "stageName": stage-name, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": deployment-id, "lastUpdatedDate": 1533849811, "createdDate": 1533849811, "methodSettings": {} } ``` The following [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) turns on active X-Ray tracing for a deployed API: ``` aws apigateway update-stage \ --rest-api-id rest-api-id \ --stage-name stage-name \ --patch-operations op=replace,path=/tracingEnabled,value=true ``` The following [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) turns off active X-Ray tracing for a deployed API: ``` aws apigateway update-stage \ --rest-api-id rest-api-id \ --stage-name stage-name \ --region region \ --patch-operations op=replace,path=/tracingEnabled,value=false ``` The output will look like the following: ``` { "tracingEnabled": false, "stageName": stage-name, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": deployment-id, "lastUpdatedDate": 1533850033, "createdDate": 1533849811, "methodSettings": {} } ``` Once you've enabled X-Ray for your API stage, use the X-Ray CLI to retrieve trace information. For more information, see [Using the X-Ray API with the AWS CLI](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-tutorial). # Use AWS X-Ray service maps and trace views with API Gateway In this section you can find detailed information on how to use [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) service maps and trace views with API Gateway. **Topics** + [Example X-Ray service map](#apigateway-using-xray-maps-active) + [Example X-Ray trace view](#apigateway-using-xray-trace-view-active) ## Example X-Ray service map AWS X-Ray service maps show information about your API and all of its downstream services. When X-Ray is enabled for an API stage in API Gateway, you'll see a node in the service map containing information about the overall time spent in the API Gateway service. You can get detailed information about the response status and a histogram of the API response time for the selected timeframe. For APIs integrating with AWS services such as AWS Lambda and Amazon DynamoDB, you will see more nodes providing performance metrics related to those services. There will be a service map for each API stage. The following example shows a service map for the `test` stage of an API called `xray`. This API has two Lambda integrations. The nodes represent the API Gateway service and the two Lambda functions. For a detailed explanation of service map structure, see [Use the X-Ray trace map](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-servicemap). ![\[Service map example of an API Gateway API stage\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/apigateway-xray-servicemap-2.png) From the service map, you can zoom in to see a trace view of your API stage. The trace will display in-depth information regarding your API, represented as segments and subsegments. For example, the trace for the service map shown above would include segments for the Lambda service and Lambda function. For more information, see [AWS Lambda and AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-lambda.html). If you choose a node or edge on an X-Ray service map, the X-Ray console shows a latency distribution histogram. You can use a latency histogram to see how long it takes for a service to complete its requests. Following is a histogram of the API Gateway stage named `xray/test` in the previous service map. For a detailed explanation of latency distribution histograms, see [Use Latency Histograms](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-histograms). ![\[X-Ray histogram of an API Gateway API stage\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/apigateway-xray-histogram-1.png) ## Example X-Ray trace view The following diagram shows a trace view generated for the example API described above, with a Lambda backend function. A successful API method request is shown with a response code of 200. For a detailed explanation of trace views, see [View traces and trace details](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-traces). ![\[API Gateway with active tracing enabled\]](http://docs.aws.amazon.com/apigateway/latest/developerguide/images/apigateway-xray-traceview-1.png) # Configure AWS X-Ray sampling rules for API Gateway APIs You can use AWS X-Ray console or SDK to configure sampling rules for your Amazon API Gateway API. A sampling rule specifies which requests X-Ray should record for your API. By customizing sampling rules, you can control the amount of data that you record, and modify sampling behavior on the fly without modifying or redeploying your code. Before you specify your X-Ray sampling rules, read the following topics in the X-Ray Developer Guide: + [Configure sampling rules](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling) + [Using Sampling Rules with the X-Ray API](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-sampling) **Topics** + [X-Ray sampling rule option values for API Gateway APIs](#apigateway-xray-sampling-rule-options) + [X-Ray sampling rule examples](#apigateway-xray-sampling-rules-examples) ## X-Ray sampling rule option values for API Gateway APIs The following X-Ray sampling options are relevant for API Gateway. String values can use wildcards to match a single character (?) or zero or more characters (\$1). For more details, including a detailed explanation of how the **Reservoir** and **Rate** settings are used, [Configure sampling rules](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling). + **Rule name** (string) — A unique name for the rule. + **Priority** (integer between 1 and 9999) — The priority of the sampling rule. Services evaluate rules in ascending order of priority, and make a sampling decision with the first rule that matches. + **Reservoir** (nonnegative integer) — A fixed number of matching requests to instrument per second, before applying the fixed rate. The reservoir is not used directly by services, but applies to all services using the rule collectively. + **Rate** (number between 0 and 100) — The percentage of matching requests to instrument, after the reservoir is exhausted. + **Service name** (string) — API stage name, in the form ***\$1api-name\$1*/*\$1stage-name\$1***. For example, if you were to deploy the [PetStore](api-gateway-create-api-from-example.md) sample API to a stage named `test`, the **Service name** value to specify in your sampling rule would be **pets/test**. + **Service type** (string) — For an API Gateway API, either **AWS::ApiGateway::Stage** or **AWS::ApiGateway::\$1** can be specified. + **Host** (string) — The hostname from the HTTP host header. Set this to **\$1** to match against all hostnames. Or you can specify a full or partial hostname to match, for example, **api.example.com** or **\$1.example.com**. + **Resource ARN** (string) — The ARN of the API stage, for example, **arn:aws:apigateway:*region*::/restapis/*api-id*/stages/*stage-name***. The stage name can be obtained from the console or the API Gateway CLI or API. For more information about ARN formats, see the [Amazon Web Services General Reference](https://docs.aws.amazon.com/general/latest/gr/). + **HTTP method** (string) — The method to be sampled, for example, **GET**. + **URL path** (string) — The URL path of the request. + (optional) **Attributes** (key and value) — Headers from the original HTTP request, for example, **Connection**, **Content-Length**, or **Content-Type**. Each attribute value can be up to 32 characters long. ## X-Ray sampling rule examples **Sampling rule example \$11** This rule samples all `GET` requests for the `testxray` API at the `test` stage. + **Rule name — ****test-sampling** + **Priority — ****17** + **Reservoir size — ****10** + **Fixed rate — ****10** + **Service name — ****testxray/test** + **Service type — ****AWS::ApiGateway::Stage** + **HTTP method — ****GET** + **Resource ARN — ****\$1** + **Host — ****\$1** **Sampling rule example \$12** This rule samples all requests for the `testxray` API at the `prod` stage. + **Rule name — ****prod-sampling** + **Priority — ****478** + **Reservoir size — ****1** + **Fixed rate — ****60** + **Service name — ****testxray/prod** + **Service type — ****AWS::ApiGateway::Stage** + **HTTP method — ****\$1** + **Resource ARN — ****\$1** + **Host — ****\$1** + **Attributes** — **\$1\$1** # AWS X-Ray traces for Amazon API Gateway APIs This section discusses AWS X-Ray trace segments, subsegments, and other trace fields for Amazon API Gateway APIs. Before you read this section, review the following topics in the X-Ray Developer Guide: + [Use an AWS Management Console](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html) + [X-Ray segment documents](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-segmentdocuments) + [Concepts](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html#xray-concepts) **Topics** + [Examples of trace objects for an API Gateway API](#apigateway-understanding-xray-traces-example-segments) + [Understanding the trace](#apigateway-understanding-xray-traces-segments) ## Examples of trace objects for an API Gateway API This section discusses some of the objects you may see in a trace for an API Gateway API. **Annotations** Annotations can appear in segments and subsegments. They are used as filtering expressions in sampling rules to filter traces. For more information, see [Configure sampling rules](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling). Following is an example of an `annotations` object, in which an API stage is identified by the API ID and the API stage name: ``` "annotations": { "aws:api_id": "a1b2c3d4e5", "aws:api_stage": "dev" } ``` For more information about annotations, see [X-Ray segment documents](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-segmentdocuments), and then choose **X-Ray segment documents**, **Annotations**. **AWS resource data** The `aws` object appears only in segments. Following is an example of an `aws` object that matches the Default sampling rule. For an in-depth explanation of sampling rules, see [Configure sampling rules](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling). ``` "aws": { "xray": { "sampling_rule_name": "Default" }, "api_gateway": { "account_id": "123412341234", "rest_api_id": "a1b2c3d4e5", "stage": "dev", "request_id": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6" } } ``` For more information about the `aws` object, see [X-Ray segment documents](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-segmentdocuments), and then choose **X-Ray segment documents**, **AWS resource data**. ## Understanding the trace Following is a trace segment for an API Gateway stage. For a detailed explanation of the fields that make up the trace segment, see [X-Ray segment documents](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-segmentdocuments). ``` { "Document": { "id": "a1b2c3d4a1b2c3d4", "name": "testxray/dev", "start_time": 1533928226.229, "end_time": 1533928226.614, "metadata": { "default": { "extended_request_id": "abcde12345abcde=", "request_id": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6" } }, "http": { "request": { "url": "https://example.com/dev?username=demo&message=hellofromdemo/", "method": "GET", "client_ip": "192.0.2.0", "x_forwarded_for": true }, "response": { "status": 200, "content_length": 0 } }, "aws": { "xray": { "sampling_rule_name": "Default" }, "api_gateway": { "account_id": "123412341234", "rest_api_id": "a1b2c3d4e5", "stage": "dev", "request_id": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6" } }, "annotations": { "aws:api_id": "a1b2c3d4e5", "aws:api_stage": "dev" }, "trace_id": "1-a1b2c3d4-a1b2c3d4a1b2c3d4a1b2c3d4", "origin": "AWS::ApiGateway::Stage", "resource_arn": "arn:aws:apigateway:us-east-1::/restapis/a1b2c3d4e5/stages/dev", "subsegments": [ { "id": "abcdefgh12345678", "name": "Lambda", "start_time": 1533928226.233, "end_time": 1533928226.6130002, "http": { "request": { "url": "https://example.com/2015-03-31/functions/arn:aws:lambda:us-east-1:123412341234:function:xray123/invocations", "method": "GET" }, "response": { "status": 200, "content_length": 62 } }, "aws": { "function_name": "xray123", "region": "us-east-1", "operation": "Invoke", "resource_names": [ "xray123" ] }, "namespace": "aws" } ] }, "Id": "a1b2c3d4a1b2c3d4" } ```