# Monitor REST APIs in API Gateway Monitor In this section, you can learn how to monitor your API by using CloudWatch metrics, CloudWatch Logs, Firehose, and AWS X-Ray. By combining CloudWatch execution logs and CloudWatch metrics, you can log errors and execution traces, and monitor your API's performance. You might also want to log API calls to Firehose. You can also use AWS X-Ray to trace calls through the downstream services that make up your API. **Note** API Gateway might not generate logs and metrics in the following cases: 413 Request Entity Too Large errors 431 Request Header Fields Too Large errors Excessive 429 Too Many Requests errors 400 series errors from requests sent to a custom domain that has no API mapping 500 series errors caused by internal failures API Gateway will not generate logs and metrics when testing a REST API method. The CloudWatch entries are simulated. For more information, see [Use the API Gateway console to test a REST API method](how-to-test-method.md). **Topics** + [ # Monitor REST API execution with Amazon CloudWatch metrics ](monitoring-cloudwatch.md) + [ # Set up CloudWatch logging for REST APIs in API Gateway ](set-up-logging.md) + [ # Log REST API calls to Amazon Data Firehose in API Gateway ](apigateway-logging-to-kinesis.md) + [ # Variables for access logging for API Gateway ](api-gateway-variables-for-access-logging.md) + [ # Trace user requests to REST APIs using X-Ray in API Gateway ](apigateway-xray.md) # Monitor REST API execution with Amazon CloudWatch metrics CloudWatch metrics You can monitor API execution by using CloudWatch, which collects and processes raw data from API Gateway into readable, near-real-time metrics. These statistics are recorded for a period of 15 months so you can access historical information and gain a better perspective on how your web application or service is performing. By default, API Gateway metric data is automatically sent to CloudWatch in one-minute periods. For more information, see [What Is Amazon CloudWatch?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) in the *Amazon CloudWatch User Guide*. The metrics reported by API Gateway provide information that you can analyze in different ways. The following list shows some common uses for the metrics that are suggestions to get you started: + Monitor the **IntegrationLatency** metrics to measure the responsiveness of the backend. + Monitor the **Latency** metrics to measure the overall responsiveness of your API calls. + Monitor the **CacheHitCount** and **CacheMissCount** metrics to optimize cache capacities to achieve a desired performance. **Topics** + [ # Amazon API Gateway dimensions and metrics ](api-gateway-metrics-and-dimensions.md) + [ # View CloudWatch metrics with the API dashboard in API Gateway ](how-to-api-dashboard.md) + [ # View API Gateway metrics in the CloudWatch console ](metrics_dimensions_view_in_cloud_watch.md) + [ # View API Gateway log events in the CloudWatch console ](view-cloudwatch-log-events-in-cloudwatch-console.md) + [ # Monitoring tools in AWS for API Gateway ](monitoring_automated_manual.md) # Amazon API Gateway dimensions and metrics The metrics and dimensions that API Gateway sends to Amazon CloudWatch are listed below. For more information, see [Monitor REST API execution with Amazon CloudWatch metrics](monitoring-cloudwatch.md). ## API Gateway metrics Amazon API Gateway sends metric data to CloudWatch every minute. The `AWS/ApiGateway` namespace includes the following metrics. | Metric | Description | | --- | --- | | 4XXError | The number of client-side errors captured in a given period. API Gateway counts modified gateway response status codes as 4XXError errors. The `Sum` statistic represents this metric, namely, the total count of the 4XXError errors in the given period. The `Average` statistic represents the 4XXError error rate, namely, the total count of the 4XXError errors divided by the total number of requests during the period. The denominator corresponds to the Count metric (below). Unit: Count | | 5XXError | The number of server-side errors captured in a given period. The `Sum` statistic represents this metric, namely, the total count of the 5XXError errors in the given period. The `Average` statistic represents the 5XXError error rate, namely, the total count of the 5XXError errors divided by the total number of requests during the period. The denominator corresponds to the Count metric (below). Unit: Count | | CacheHitCount | The number of requests served from the API cache in a given period. The `Sum` statistic represents this metric, namely, the total count of the cache hits in the given period. The `Average` statistic represents the cache hit rate, namely, the total count of the cache hits divided by the total number of requests during the period. The denominator corresponds to the Count metric (below). Unit: Count | | CacheMissCount | The number of requests served from the backend in a given period, when API caching is enabled. The `Sum` statistic represents this metric, namely, the total count of the cache misses in the given period. The `Average` statistic represents the cache miss rate, namely, the total count of the cache misses divided by the total number of requests during the period. The denominator corresponds to the Count metric (below). Unit: Count | | Count | The total number API requests in a given period. The `SampleCount` statistic represents this metric. Unit: Count | | IntegrationLatency | The time between when API Gateway relays a request to the backend and when it receives a response from the backend. Unit: Millisecond | | Latency | The time between when API Gateway receives a request from a client and when it returns a response to the client. The latency includes the integration latency and other API Gateway overhead. Unit: Millisecond | ## Dimensions for metrics You can use the dimensions in the following table to filter API Gateway metrics. **Note** API Gateway removes non-ASCII characters from the ApiName dimension before sending metrics to CloudWatch. If the APIName contains no ASCII characters, the API ID is used as the ApiName. | Dimension | Description | | --- | --- | | ApiName | Filters API Gateway metrics for the REST API with the specified API name. | | ApiName, Method, Resource, Stage | Filters API Gateway metrics for the API method with the specified API name, stage, resource, and method. API Gateway will not send these metrics unless you have explicitly enabled detailed CloudWatch metrics. In the console, choose a stage, and then for **Logs and tracing**, select **Edit**. Select **Detailed metrics**, and then choose **Save changes**. Alternatively, you can call the [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) AWS CLI command to update the `metricsEnabled` property to `true`. Enabling these metrics will incur additional charges to your account. For pricing information, see [Amazon CloudWatch Pricing](https://aws.amazon.com/cloudwatch/pricing/). | | ApiName, Stage | Filters API Gateway metrics for the API stage resource with the specified API name and stage. | # View CloudWatch metrics with the API dashboard in API Gateway View metrics with the API dashboard You can use the API dashboard in the API Gateway Console to display the CloudWatch metrics of your deployed API in API Gateway. These are shown as a summary of API activity over time. **Topics** + [ ## Prerequisites ](#how-to-api-dashboard-prerequisites) + [ ## Examine API activities in the dashboard ](#how-to-api-dashboard-console) ## Prerequisites 1. You must have an API created in API Gateway. Follow the instructions in [Develop REST APIs in API Gateway](rest-api-develop.md). 1. You must have the API deployed at least once. Follow the instructions in [Deploy REST APIs in API Gateway](how-to-deploy-api.md). ## Examine API activities in the dashboard 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Choose an API. 1. In the main navigation pane, choose **Dashboard**. 1. For **Stage**, choose the desired stage. 1. Choose **Date range** to specify a range of dates. 1. Refresh, if needed, and view individual metrics displayed in separate graphs titled **API calls**, **Latency**, **Integration latency**, **Latency**, **4xx error** and **5xx error**. **Tip** To examine method-level CloudWatch metrics, make sure that you have enabled CloudWatch Logs on a method level. For more information about how to set up method-level logging, see [Override stage-level settings](set-up-stages.md#how-to-method-override). # View API Gateway metrics in the CloudWatch console View metrics in the CloudWatch console Metrics are grouped first by the service namespace, and then by the various dimension combinations within each namespace. To view the metrics at the method-level for your API, turn on detailed metrics. For more information, see [Modify stage settings](set-up-stages.md#how-to-stage-settings). **To view API Gateway metrics using the CloudWatch console** 1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. If necessary, change the AWS Region. From the navigation bar, select the Region where your AWS resources reside. 1. In the navigation pane, choose **Metrics**. 1. In the **All metrics** tab, choose **API Gateway**. 1. To view metrics by stage, choose the **By Stage** panel. Then, select your APIs and metric names. 1. To view metrics by specific API, choose the **By Api Name** panel. Then, select your APIs and metric names. **To view metrics using the AWS CLI** 1. Use the following [list-metrics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/list-metrics.html) command to list metrics: ``` aws cloudwatch list-metrics --namespace "AWS/ApiGateway" ``` After you create a metric, allow up to 15 minutes for the metric to appear. To see metric statistics sooner, use [get-metric-data](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/update-domain-name.html) or [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/update-domain-name.html). 1. Use the following [get-metrics-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html) command to view the average over a period of time using 5 minute intervals: ``` aws cloudwatch get-metric-statistics --namespace AWS/ApiGateway --metric-name Count --start-time 2011-10-03T23:00:00Z --end-time 2017-10-05T23:00:00Z --period 300 --statistics Average ``` # View API Gateway log events in the CloudWatch console View log event in the CloudWatch console The following section explains the necessary prerequisites and how to view API Gateway log events in the CloudWatch console. ## Prerequisites 1. You must have an API created in API Gateway. Follow the instructions in [Develop REST APIs in API Gateway](rest-api-develop.md). 1. You must have the API deployed and invoked at least once. Follow the instructions in [Deploy REST APIs in API Gateway](how-to-deploy-api.md) and [Invoke REST APIs in API Gateway](how-to-call-api.md). 1. You must have CloudWatch Logs enabled for a stage. Follow the instructions in [Set up CloudWatch logging for REST APIs in API Gateway](set-up-logging.md). ## To view logged API requests and responses using the CloudWatch console 1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. If necessary, change the AWS Region. From the navigation bar, select the Region where your AWS resources reside. For more information, see [Regions and Endpoints](http://docs.aws.amazon.com/general/latest/gr/rande.html). 1. In the navigation pane, choose **Logs**, **Log groups**. 1. Under the **Log Groups** table, choose a log group of the **API-Gateway-Execution-Logs\$1\$1rest-api-id\$1/\$1stage-name\$1** name. 1. Under the **Log Streams** table, choose a log stream. You can use the timestamp to help locate the log stream of your interest. 1. Choose **Text** to view raw text or choose **Row** to view the event row by row. **Important** CloudWatch lets you delete log groups or streams. Do not manually delete API Gateway API log groups or streams; let API Gateway manage these resources. Manually deleting log groups or streams may cause API requests and responses not to be logged. If that happens, you can delete the entire log group for the API and redeploy the API. This is because API Gateway creates log groups or log streams for an API stage at the time when it is deployed. # Monitoring tools in AWS for API Gateway AWS provides various tools that you can use to monitor API Gateway. You can configure some of these tools to do the monitoring for you automatically, while other tools require manual intervention. We recommend that you automate monitoring tasks as much as possible. ## Automated monitoring tools in AWS Automated monitoring tools You can use the following automated monitoring tools to watch API Gateway and report when something is wrong: + **Amazon CloudWatch Alarms** – Watch a single metric over a time period that you specify, and perform one or more actions based on the value of the metric relative to a given threshold over a number of time periods. The action is a notification sent to an Amazon Simple Notification Service (Amazon SNS) topic or Amazon EC2 Auto Scaling policy. CloudWatch alarms do not invoke actions simply because they are in a particular state; the state must have changed and been maintained for a specified number of periods. For more information, see [Monitor REST API execution with Amazon CloudWatch metrics](monitoring-cloudwatch.md). + **Amazon CloudWatch Logs** – Monitor, store, and access your log files from AWS CloudTrail or other sources. For more information, see [What is CloudWatch Logs?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) in the *Amazon CloudWatch User Guide*. + **Amazon EventBridge (formerly called CloudWatch Events)** – Match events and route them to one or more target functions or streams to make changes, capture state information, and take corrective action. For more information, see [What Is Amazon EventBridge?](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) in the *EventBridge User Guide*. + **AWS CloudTrail Log Monitoring** – Share log files between accounts, monitor CloudTrail log files in real time by sending them to CloudWatch Logs, write log processing applications in Java, and validate that your log files have not changed after delivery by CloudTrail. For more information, see [Working with CloudTrail Log Files](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-working-with-log-files.html) in the *AWS CloudTrail User Guide*. ## Manual monitoring tools Manual tools Another important part of monitoring API Gateway involves manually monitoring those items that the CloudWatch alarms don't cover. The API Gateway, CloudWatch, and other AWS console dashboards provide an at-a-glance view of the state of your AWS environment. We recommend that you also check the log files on API execution. + API Gateway dashboard shows the following statistics for a given API stage during a specified period of time: + **API Calls** + **Cache Hit**, only when API caching is enabled. + **Cache Miss**, only when API caching is enabled. + **Latency** + **Integration Latency** + **4XX Error** + **5XX Error** + The CloudWatch home page shows: + Current alarms and status + Graphs of alarms and resources + Service health status In addition, you can use CloudWatch to do the following: + Create [customized dashboards](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html) to monitor the services you care about + Graph metric data to troubleshoot issues and discover trends + Search and browse all your AWS resource metrics + Create and edit alarms to be notified of problems ## Creating CloudWatch alarms to monitor API Gateway Creating alarms You can create a CloudWatch alarm that sends an Amazon SNS message when the alarm changes state. An alarm watches a single metric over a time period you specify, and performs one or more actions based on the value of the metric relative to a given threshold over a number of time periods. The action is a notification sent to an Amazon SNS topic or Auto Scaling policy. Alarms invoke actions for sustained state changes only. CloudWatch alarms do not invoke actions simply because they are in a particular state; the state must have changed and been maintained for a specified number of periods. # Set up CloudWatch logging for REST APIs in API Gateway CloudWatch logs To help debug issues related to request execution or client access to your API, you can enable Amazon CloudWatch Logs to log API calls. For more information about CloudWatch, see [Monitor REST API execution with Amazon CloudWatch metrics](monitoring-cloudwatch.md). ## CloudWatch log formats for API Gateway There are two types of API logging in CloudWatch: execution logging and access logging. In execution logging, API Gateway manages the CloudWatch Logs. The process includes creating log groups and log streams, and reporting to the log streams any caller's requests and responses. The logged data includes errors or execution traces (such as request or response parameter values or payloads), data used by Lambda authorizers (formerly known as custom authorizers), whether API keys are required, whether usage plans are enabled, and other information. API Gateway redacts authorization headers, API key values, and similar sensitive request parameters from the logged data. To improve your security posture, we recommend that you use execution logging at the `ERROR` or `INFO` level. You might need to do this to comply with various compliance frameworks. For more information, see [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) in the *AWS Security Hub User Guide*. When you deploy an API, API Gateway creates a log group and log streams under the log group. The log group is named following the `API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}` format. Within each log group, the logs are further divided into log streams, which are ordered by **Last Event Time** as logged data is reported. In access logging, you, as an API developer, want to log who has accessed your API and how the caller accessed the API. You can create your own log group or choose an existing log group that could be managed by API Gateway. To specify the access details, you select [`$context`](api-gateway-variables-for-access-logging.md) variables, a log format, and a log group destination. The access log format must include at least `$context.requestId` or `$context.extendedRequestId`. As a best practice, include `$context.requestId` and `$context.extendedRequestId` in your log format. **`$context.requestId`** This logs the value in the `x-amzn-RequestId` header. Clients can override the value in the `x-amzn-RequestId` header with a value in the format of a universally unique identifier (UUID). API Gateway returns this request ID in the `x-amzn-RequestId` response header. API Gateway replaces overridden request IDs that aren't in the format of a UUID with `UUID_REPLACED_INVALID_REQUEST_ID` in your access logs. **`$context.extendedRequestId`** The extendedRequestID is a unique ID that API Gateway generates. API Gateway returns this request ID in the `x-amz-apigw-id` response header. An API caller can't provide or override this request ID. You might need to provide this value to AWS Support to help troubleshoot your API. For more information, see [Variables for access logging for API Gateway](api-gateway-variables-for-access-logging.md). Choose a log format that is also adopted by your analytic backend, such as [Common Log Format](https://httpd.apache.org/docs/current/logs.html#common) (CLF), JSON, XML, or CSV. You can then feed the access logs to it directly to have your metrics computed and rendered. To define the log format, set the log group ARN on the [accessLogSettings/destinationArn](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#destinationArn) property on the [stage](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html). You can obtain a log group ARN in the CloudWatch console. To define the access log format, set a chosen format on the [accessLogSetting/format](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#format) property on the [stage](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html). Examples of some commonly used access log formats are shown in the API Gateway console and are listed as follows. + `CLF` ([Common Log Format](https://httpd.apache.org/docs/current/logs.html#common)): ``` $context.identity.sourceIp $context.identity.caller $context.identity.user [$context.requestTime]"$context.httpMethod $context.resourcePath $context.protocol" $context.status $context.responseLength $context.requestId $context.extendedRequestId ``` + `JSON`: ``` { "requestId":"$context.requestId", "extendedRequestId":"$context.extendedRequestId","ip": "$context.identity.sourceIp", "caller":"$context.identity.caller", "user":"$context.identity.user", "requestTime":"$context.requestTime", "httpMethod":"$context.httpMethod", "resourcePath":"$context.resourcePath", "status":"$context.status", "protocol":"$context.protocol", "responseLength":"$context.responseLength" } ``` + `XML`: ``` $context.extendedRequestId $context.identity.sourceIp $context.identity.caller $context.identity.user $context.requestTime $context.httpMethod $context.resourcePath $context.status $context.protocol $context.responseLength ``` + `CSV` (comma-separated values): ``` $context.identity.sourceIp,$context.identity.caller,$context.identity.user,$context.requestTime,$context.httpMethod,$context.resourcePath,$context.protocol,$context.status,$context.responseLength,$context.requestId,$context.extendedRequestId ``` ## Permissions for CloudWatch logging To enable CloudWatch Logs, you must grant API Gateway permission to read and write logs to CloudWatch for your account. The [AmazonAPIGatewayPushToCloudWatchLogs](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAPIGatewayPushToCloudWatchLogs.html) has all the required permissions. **Note** API Gateway calls AWS Security Token Service in order to assume the IAM role, so make sure that AWS STS is enabled for the Region. For more information, see [Managing AWS STS in an AWS Region](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html). To grant these permissions to your account, create an IAM role with `apigateway.amazonaws.com` as its trusted entity, attach the preceding policy to the IAM role, and set the IAM role ARN on the [cloudWatchRoleArn](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html#cloudWatchRoleArn) property on your [Account](https://docs.aws.amazon.com/apigateway/latest/api/API_GetAccount.html). You must set the [cloudWatchRoleArn](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html#cloudWatchRoleArn) property separately for each AWS Region in which you want to enable CloudWatch Logs. If you receive an error when setting the IAM role ARN, check your AWS Security Token Service account settings to make sure that AWS STS is enabled in the Region that you're using. For more information about enabling AWS STS, see [Managing AWS STS in an AWS Region](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html#sts-regions-activate-deactivate) in the *IAM User Guide*. ## Set up CloudWatch API logging using the API Gateway console To set up CloudWatch API logging, you must have deployed the API to a stage. You must also have configured [an appropriate CloudWatch Logs role](#set-up-access-logging-permissions) ARN for your account. 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. On the main navigation pane, choose **Settings**, and then under **Logging**, choose **Edit**. 1. For **CloudWatch log role ARN**, enter an ARN of an IAM role with appropriate permissions. You need to do this once for each AWS account that creates APIs using API Gateway. 1. In the main navigation pane, choose **APIs**, and then do one of the following: 1. Choose an existing API, and then choose a stage. 1. Create an API, and then deploy it to a stage. 1. In the main navigation pane, choose **Stages**. 1. In the **Logs and tracing** section, choose **Edit**. 1. To enable execution logging: 1. Select a logging level from the **CloudWatch Logs** dropdown menu. The logging levels are the following: + **Off** – Logging is not turned on for this stage. + **Errors only** – Logging is enabled for errors only. + **Errors and info logs** – Logging is enabled for all events. 1. (Optional) Select **Data tracing** to turn on data trace logging for your stage. This can be useful to troubleshoot APIs, but can result in logging sensitive data. **Note** We recommend that you don't use **Data tracing** for production APIs. 1. (Optional) Select **Detailed metrics** to turn on detailed CloudWatch metrics. For more information about CloudWatch metrics, see [Monitor REST API execution with Amazon CloudWatch metrics](monitoring-cloudwatch.md). 1. To enable access logging: 1. Turn on **Custom access logging**. 1. For **Access log destination ARN**, enter the ARN of a log group. The ARN format is `arn:aws:logs:{region}:{account-id}:log-group:log-group-name`. 1. For **Log Format**, enter a log format. You can choose **CLF**, **JSON**, **XML**, or **CSV**. To learn more about example log formats, see [CloudWatch log formats for API Gateway](#apigateway-cloudwatch-log-formats). 1. Choose **Save changes**. **Note** You can enable execution logging and access logging independently of each other. API Gateway is now ready to log requests to your API. You don't need to redeploy the API when you update the stage settings, logs, or stage variables. ## Set up CloudWatch API logging using CloudFormation Use the following example CloudFormation template to create an Amazon CloudWatch Logs log group and configure execution and access logging for a stage. To enable CloudWatch Logs, you must grant API Gateway permission to read and write logs to CloudWatch for your account. To learn more, see [Associate account with IAM role](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-account.html#aws-resource-apigateway-account--examples) in the *AWS CloudFormation User Guide*. ``` TestStage: Type: AWS::ApiGateway::Stage Properties: StageName: test RestApiId: !Ref MyAPI DeploymentId: !Ref Deployment Description: "test stage description" MethodSettings: - ResourcePath: "/*" HttpMethod: "*" LoggingLevel: INFO AccessLogSetting: DestinationArn: !GetAtt MyLogGroup.Arn Format: $context.extendedRequestId $context.identity.sourceIp $context.identity.caller $context.identity.user [$context.requestTime] "$context.httpMethod $context.resourcePath $context.protocol" $context.status $context.responseLength $context.requestId MyLogGroup: Type: AWS::Logs::LogGroup Properties: LogGroupName: !Join - '-' - - !Ref MyAPI - access-logs ``` # Log REST API calls to Amazon Data Firehose in API Gateway Firehose To help debug issues related to client access to your API, you can log API calls to Amazon Data Firehose. For more information about Firehose, see [What Is Amazon Data Firehose?](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html). For access logging, you can only enable CloudWatch or Firehose—you can't enable both. However, you can enable CloudWatch for execution logging and Firehose for access logging. **Topics** + [ ## Firehose log formats for API Gateway ](#apigateway-kinesis-log-formats) + [ ## Permissions for Firehose logging ](#set-up-kinesis-access-logging-permissions) + [ ## Set up Firehose access logging by using the API Gateway console ](#set-up-kinesis-access-logging-using-console) ## Firehose log formats for API Gateway Firehose logging uses the same format as [CloudWatch logging](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-logging.html). ## Permissions for Firehose logging When Firehose access logging is enabled on a stage, API Gateway creates a service-linked role in your account if the role doesn't exist already. The role is named `AWSServiceRoleForAPIGateway` and has 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** The name of your Firehose stream must be `amazon-apigateway-{your-stream-name}`. ## Set up Firehose access logging by using the API Gateway console To set up API logging, you must have deployed the API to a stage. You must also have created a Firehose stream. 1. Sign in to the API Gateway console at [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Do one of the following: 1. Choose an existing API, and then choose a stage. 1. Create an API and deploy it to a stage. 1. In the main navigation pane, choose **Stages**. 1. In the **Logs and tracing** section, choose **Edit**. 1. To enable access logging to a Firehose stream: 1. Turn on **Custom access logging**. 1. For **Access log destination ARN**, enter the ARN of a Firehose stream. The ARN format is `arn:aws:firehose:{region}:{account-id}:deliverystream/amazon-apigateway-{your-stream-name}`. **Note** The name of your Firehose stream must be `amazon-apigateway-{your-stream-name}`. 1. For **Log format**, enter a log format. You can choose **CLF**, **JSON**, **XML**, or **CSV**. To learn more about example log formats, see [CloudWatch log formats for API Gateway](set-up-logging.md#apigateway-cloudwatch-log-formats). 1. Choose **Save changes**. API Gateway is now ready to log requests to your API to Firehose. You don't need to redeploy the API when you update the stage settings, logs, or stage variables. # Variables for access logging for API Gateway In access logging, you, as an API developer, want to log who has accessed your API and how the caller accessed the API. You can create your own log group or choose an existing log group that could be managed by API Gateway. To specify the access details, you can use the following case-sensitive `$context` variables. For a list of reference variables for data transformations, see [Variables for data transformations for API Gateway](api-gateway-mapping-template-reference.md). | Parameter | Description | | --- | --- | | \$1context.accountId | The API owner's AWS account ID. | | \$1context.apiId | The identifier API Gateway assigns to your API. | | \$1context.authorize.error | The authorization error message. | | \$1context.authorize.latency | The authorization latency in ms. | | \$1context.authorize.status | The status code returned from an authorization attempt. | | \$1context.authorizer.claims.property | A property of the claims returned from the Amazon Cognito user pool after the method caller is successfully authenticated. For more information, see [Control access to REST APIs using Amazon Cognito user pools as an authorizer](apigateway-integrate-with-cognito.md). Calling `$context.authorizer.claims` returns null. | | \$1context.authorizer.error | The error message returned from an authorizer. | | \$1context.authorizer.integrationLatency | The authorizer integration latency in ms. | | \$1context.authorizer.integrationStatus | The status code returned from a Lambda authorizer. | | \$1context.authorizer.latency | The authorizer latency in ms. | | \$1context.authorizer.principalId | The principal user identification associated with the token sent by the client and returned from an API Gateway Lambda authorizer (formerly known as a custom authorizer). For more information, see [Use API Gateway Lambda authorizers](apigateway-use-lambda-authorizer.md). | | \$1context.authorizer.property | The stringified value of the specified key-value pair of the `context` map returned from an API Gateway Lambda authorizer function. For example, if the authorizer returns the following `context` map: 
"context" : {
  "key": "value",
  "numKey": 1,
  "boolKey": true
}
Calling `$context.authorizer.key` returns the `"value"` string, calling `$context.authorizer.numKey` returns the `"1"` string, and calling `$context.authorizer.boolKey` returns the `"true"` string. For *property*, the only supported special character is the underscore `(_)` character. For more information, see [Use API Gateway Lambda authorizers](apigateway-use-lambda-authorizer.md). | | \$1context.authorizer.requestId | The AWS endpoint's request ID. | | \$1context.authorizer.status | The status code returned from an authorizer. | | \$1context.authenticate.error | The error message returned from an authentication attempt. | | \$1context.authenticate.latency | The authentication latency in ms. | | \$1context.authenticate.status | The status code returned from an authentication attempt. | | \$1context.awsEndpointRequestId | The AWS endpoint's request ID. | | \$1context.cipherSuite | The cipher, in IANA format, that is negotiated during the TLS handshake between the client and API Gateway. | | \$1context.customDomain.basePathMatched | The path for an API mapping that an incoming request matched. Applicable when a client uses a custom domain name to access an API. For example if a client sends a request to `https://api.example.com/v1/orders/1234`, and the request matches the API mapping with the path `v1/orders`, the value is `v1/orders`. To learn more, see [Use API mappings to connect API stages to a custom domain name for REST APIs](rest-api-mappings.md). | | \$1context.customDomain.routingRuleIdMatched | The routing rule that an incoming request matched. Applicable when a client uses a custom domain name to access an API. To learn more, see [Routing rules to connect API stages to a custom domain name for REST APIs](rest-api-routing-rules.md). | | \$1context.deploymentId | The ID of the API deployment. | | \$1context.domainName | The full domain name used to invoke the API. This should be the same as the incoming `Host` header. | | \$1context.domainPrefix | The first label of the `$context.domainName`. | | \$1context.endpointType | The endpoint type of the API. | | \$1context.error.message | A string containing an API Gateway error message. This variable can only be used for simple variable substitution in a [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) body-mapping template, which is not processed by the Velocity Template Language engine, and in access logging. For more information, see [Monitor WebSocket API execution with CloudWatch metrics](apigateway-websocket-api-logging.md) and [Setting up gateway responses to customize error responses](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). | | \$1context.error.messageString | The quoted value of \$1context.error.message, namely "\$1context.error.message". | | \$1context.error.responseType | A [type](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) of [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html). This variable can only be used for simple variable substitution in a [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html) body-mapping template, which is not processed by the Velocity Template Language engine, and in access logging. For more information, see [Monitor WebSocket API execution with CloudWatch metrics](apigateway-websocket-api-logging.md) and [Setting up gateway responses to customize error responses](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). | | \$1context.error.validationErrorString | A string containing a detailed validation error message. | | \$1context.extendedRequestId | The extended ID that API Gateway generates and assigns to the API request. The extended request ID contains useful information for debugging and troubleshooting. | | \$1context.httpMethod | The HTTP method used. Valid values include: `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST`, and `PUT`. | | \$1context.identity.accountId | The AWS account ID associated with the request. | | \$1context.identity.apiKey | For API methods that require an API key, this variable is the API key associated with the method request. For methods that don't require an API key, this variable is null. For more information, see [Usage plans and API keys for REST APIs in API Gateway](api-gateway-api-usage-plans.md). | | \$1context.identity.apiKeyId | The API key ID associated with an API request that requires an API key. | | \$1context.identity.caller | The principal identifier of the caller that signed the request. Supported for resources that use IAM authorization. | | \$1context.identity.cognitoAuthenticationProvider | A comma-separated list of all the Amazon Cognito authentication providers used by the caller making the request. Available only if the request was signed with Amazon Cognito credentials. For example, for an identity from an Amazon Cognito user pool, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` For information about the available Amazon Cognito authentication providers, see [Using Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) in the *Amazon Cognito Developer Guide*. | | \$1context.identity.cognitoAuthenticationType | The Amazon Cognito authentication type of the caller making the request. Available only if the request was signed with Amazon Cognito credentials. Possible values include `authenticated` for authenticated identities and `unauthenticated` for unauthenticated identities. | | \$1context.identity.cognitoIdentityId | The Amazon Cognito identity ID of the caller making the request. Available only if the request was signed with Amazon Cognito credentials. | | \$1context.identity.cognitoIdentityPoolId | The Amazon Cognito identity pool ID of the caller making the request. Available only if the request was signed with Amazon Cognito credentials. | | \$1context.identity.principalOrgId | The [AWS organization ID](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). | | \$1context.identity.sourceIp | The source IP address of the immediate TCP connection making the request to the API Gateway endpoint. | | \$1context.identity.clientCert.clientCertPem | The PEM-encoded client certificate that the client presented during mutual TLS authentication. Present when a client accesses an API by using a custom domain name that has mutual TLS enabled. Present only in access logs if mutual TLS authentication fails. | | \$1context.identity.clientCert.subjectDN | The distinguished name of the subject of the certificate that a client presents. Present when a client accesses an API by using a custom domain name that has mutual TLS enabled. Present only in access logs if mutual TLS authentication fails. | | \$1context.identity.clientCert.issuerDN | The distinguished name of the issuer of the certificate that a client presents. Present when a client accesses an API by using a custom domain name that has mutual TLS enabled. Present only in access logs if mutual TLS authentication fails. | | \$1context.identity.clientCert.serialNumber | The serial number of the certificate. Present when a client accesses an API by using a custom domain name that has mutual TLS enabled. Present only in access logs if mutual TLS authentication fails. | | \$1context.identity.clientCert.validity.notBefore | The date before which the certificate is invalid. Present when a client accesses an API by using a custom domain name that has mutual TLS enabled. Present only in access logs if mutual TLS authentication fails. | | \$1context.identity.clientCert.validity.notAfter | The date after which the certificate is invalid. Present when a client accesses an API by using a custom domain name that has mutual TLS enabled. Present only in access logs if mutual TLS authentication fails. | | \$1context.identity.vpcId | The VPC ID of the VPC making the request to the API Gateway endpoint. | | \$1context.identity.vpceId | The VPC endpoint ID of the VPC endpoint making the request to the API Gateway endpoint. Present only when you have a private API. | | \$1context.identity.user | The principal identifier of the user that will be authorized against resource access. Supported for resources that use IAM authorization. | | \$1context.identity.userAgent | The [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) header of the API caller. | | \$1context.identity.userArn | The Amazon Resource Name (ARN) of the effective user identified after authentication. For more information, see [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). | | \$1context.integration.error | The error message returned from an integration. | | \$1context.integration.integrationStatus | For Lambda proxy integration, the status code returned from AWS Lambda, not from the backend Lambda function code. | | \$1context.integration.latency | The integration latency in ms. Equivalent to \$1context.integrationLatency. | | \$1context.integration.requestId | The AWS endpoint's request ID. Equivalent to \$1context.awsEndpointRequestId. | | \$1context.integration.responseTransferMode | The response transfer mode of your integration. This can be either BUFFERED or STREAMED. | | \$1context.integration.status | The status code returned from an integration. For Lambda proxy integrations, this is the status code that your Lambda function code returns. | | \$1context.integration.timeToAllHeaders | The time between when API Gateway establishes the integration connection to when it receives all integration response headers from the client. | | \$1context.integration.timeToFirstContent | The time between when API Gateway establishes the integration connection to when it receives the first content bytes. | | \$1context.integrationLatency | The integration latency in ms. | | \$1context.integrationStatus | For Lambda proxy integration, this parameter represents the status code returned from AWS Lambda, not from the backend Lambda function code. | | \$1context.isCanaryRequest | Returns `true` if the request was directed to the canary and `false` if the request was not directed to the canary. Present only when you have a canary enabled. | | \$1context.path | The request path. For example, for a non-proxy request URL of https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child, the \$1context.path value is /\$1stage\$1/root/child. | | \$1context.protocol | The request protocol, for example, HTTP/1.1. API Gateway APIs can accept HTTP/2 requests, but API Gateway sends requests to backend integrations using HTTP/1.1. As a result, the request protocol is logged as HTTP/1.1 even if a client sends a request that uses HTTP/2. | | \$1context.requestId | An ID for the request. Clients can override this request ID. Use `$context.extendedRequestId` for a unique request ID that API Gateway generates. | | \$1context.requestOverride.header.header\$1name | The request header override. If this parameter is defined, it contains the headers to be used instead of the **HTTP Headers** that are defined in the **Integration Request** pane. For more information, see [Override your API's request and response parameters and status codes for REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestOverride.path.path\$1name | The request path override. If this parameter is defined, it contains the request path to be used instead of the **URL Path Parameters** that are defined in the **Integration Request** pane. For more information, see [Override your API's request and response parameters and status codes for REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestOverride.querystring.querystring\$1name | The request query string override. If this parameter is defined, it contains the request query strings to be used instead of the **URL Query String Parameters** that are defined in the **Integration Request** pane. For more information, see [Override your API's request and response parameters and status codes for REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.responseLatency | The response latency in ms. | | \$1context.responseLength | The response payload length in bytes. | | \$1context.responseOverride.header.header\$1name | The response header override. If this parameter is defined, it contains the header to be returned instead of the Response header that is defined as the Default mapping in the Integration Response pane. For more information, see [Override your API's request and response parameters and status codes for REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.responseOverride.status | The response status code override. If this parameter is defined, it contains the status code to be returned instead of the Method response status that is defined as the Default mapping in the Integration Response pane. For more information, see [Override your API's request and response parameters and status codes for REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestTime | The [CLF](https://httpd.apache.org/docs/current/logs.html#common)-formatted request time (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). | | \$1context.requestTimeEpoch | The [Epoch](https://en.wikipedia.org/wiki/Unix_time)-formatted request time, in milliseconds. | | \$1context.resourceId | The identifier that API Gateway assigns to your resource. | | \$1context.resourcePath | The path to your resource. For example, for the non-proxy request URI of `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`, The `$context.resourcePath` value is `/root/child`. For more information, see [Tutorial: Create a REST API with an HTTP non-proxy integration](api-gateway-create-api-step-by-step.md). | | \$1context.stage | The deployment stage of the API request (for example, `Beta` or `Prod`). | | \$1context.status | The method response status. | | \$1context.tlsVersion | The TLS version that is negotiated during the TLS handshake between the client and API Gateway. | | \$1context.waf.error | The error message returned from AWS WAF. | | \$1context.waf.latency | The AWS WAF latency in ms. | | \$1context.waf.status | The status code returned from AWS WAF. | | \$1context.xrayTraceId | The trace ID for the X-Ray trace. For more information, see [Set up AWS X-Ray with API Gateway REST APIs](apigateway-enabling-xray.md). | | \$1context.wafResponseCode | The response received from [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html): `WAF_ALLOW` or `WAF_BLOCK`. Will not be set if the stage is not associated with a web ACL. For more information, see [Use AWS WAF to protect your REST APIs in API Gateway](apigateway-control-access-aws-waf.md). | | \$1context.webaclArn | The complete ARN of the web ACL that is used to decide whether to allow or block the request. Will not be set if the stage is not associated with a web ACL. For more information, see [Use AWS WAF to protect your REST APIs in API Gateway](apigateway-control-access-aws-waf.md). | # Trace user requests to REST APIs using X-Ray in API Gateway X-Ray 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 Set up AWS X-Ray 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 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 Enabling X-Ray tracing using the API Gateway API 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 Use AWS X-Ray service maps and trace views 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 Configure AWS X-Ray sampling rules 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 X-Ray traces 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" } ```