AWS apigateway: Reorganize API Gateway CloudWatch logging docs into topic pages
Summary
The page was condensed into a short overview of execution logging and access logging, with the detailed format tables, console walkthrough, and CloudFormation sample removed and replaced by a 'Topics' list linking to new 'Execution logging for REST APIs' and 'Access logging for REST APIs' pages. Text was also lightly edited (e.g., clarifying 'managed policy' for AmazonAPIGatewayPushToCloudWatchLogs) and the execution/access logging definitions were reworded.
Security assessment
This is a documentation restructuring: logging security guidance (log levels, the warning that data tracing can log sensitive data and should not be used in production, redaction of authorization headers/API keys) is relocated to new pages rather than newly introduced, and the change does not describe or remediate any specific vulnerability or incident.
Evidence
+ * [Execution logging for REST APIs](./rest-api-execution-logging.html)
Diff
diff --git a/apigateway/latest/developerguide/set-up-logging.md b/apigateway/latest/developerguide/set-up-logging.md index 3104ba8be..851f176e0 100644 --- a//apigateway/latest/developerguide/set-up-logging.md +++ b//apigateway/latest/developerguide/set-up-logging.md @@ -7 +7 @@ -CloudWatch log formats for API GatewayPermissions for CloudWatch loggingSet up CloudWatch API logging using the API Gateway consoleSet up CloudWatch API logging using CloudFormation +Permissions for CloudWatch logging @@ -13 +13 @@ To help debug issues related to request execution or client access to your API, -## CloudWatch log formats for API Gateway +There are two types of API logging in CloudWatch: @@ -15 +15 @@ To help debug issues related to request execution or client access to your API, -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. + * **Execution logging** – API Gateway logs the actions taken to process API requests, including errors and execution traces. You can also configure Amazon CloudWatch Logs delivery to route execution logs to your own destinations. @@ -17 +17 @@ There are two types of API logging in CloudWatch: execution logging and access l -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. + * **Access logging** – You log who accessed your API and how. You create your own log group, choose a log format, and specify which `$context` variables to include. @@ -19,37 +18,0 @@ The logged data includes errors or execution traces (such as request or response -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.html) 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.html). - -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`: - - <request id="$context.requestId"> <extendedRequestId>$context.extendedRequestId</extendedRequestId> <ip>$context.identity.sourceIp</ip> <caller>$context.identity.caller</caller> <user>$context.identity.user</user> <requestTime>$context.requestTime</requestTime> <httpMethod>$context.httpMethod</httpMethod> <resourcePath>$context.resourcePath</resourcePath> <status>$context.status</status> <protocol>$context.protocol</protocol> <responseLength>$context.responseLength</responseLength> </request> - - * `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 @@ -58,0 +22 @@ Examples of some commonly used access log formats are shown in the API Gateway c +You can enable execution logging and access logging independently of each other. @@ -62 +26 @@ Examples of some commonly used access log formats are shown in the API Gateway c -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. +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) managed policy has all the required permissions. @@ -72,58 +36 @@ If you receive an error when setting the IAM role ARN, check your AWS Security T -## 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 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). - - 2. On the main navigation pane, choose **Settings** , and then under **Logging** , choose **Edit**. - - 3. 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. - - 4. In the main navigation pane, choose **APIs** , and then do one of the following: - - 1. Choose an existing API, and then choose a stage. - - 2. Create an API, and then deploy it to a stage. - - 5. In the main navigation pane, choose **Stages**. - - 6. In the **Logs and tracing** section, choose **Edit**. - - 7. 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. - - 2. (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. - - 3. (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.html). - - 8. To enable access logging: - - 1. Turn on **Custom access logging**. - - 2. 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``. - - 3. 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. - - 9. 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. +###### Topics @@ -131 +38 @@ API Gateway is now ready to log requests to your API. You don't need to redeploy -## Set up CloudWatch API logging using CloudFormation + * [Execution logging for REST APIs](./rest-api-execution-logging.html) @@ -133 +40 @@ API Gateway is now ready to log requests to your API. You don't need to redeploy -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_. + * [Access logging for REST APIs](./set-up-access-logging.html) @@ -136,21 +42,0 @@ Use the following example CloudFormation template to create an Amazon CloudWatch - 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 @@ -167 +53 @@ Monitoring tools in AWS for API Gateway -Firehose +Execution logging