Registro de ejecución para API de REST
El registro de ejecución registra las acciones que API Gateway lleva a cabo para procesar una solicitud de API. Los datos registrados contienen errores, rastros de ejecución, cargas útiles o valores de parámetros de solicitud y respuesta, datos utilizados por autorizadores Lambda, si las claves de API son necesarias y si los planes de uso están habilitados. API Gateway redacta los encabezados de autorización, los valores de las claves de API y otros parámetros de solicitud confidenciales similares a partir de los datos registrados.
Para aumentar la seguridad, le recomendamos que utilice el registro de ejecución en el nivel INFO o ERROR. Es probable que deba hacerlo para asegurar el cumplimiento de diversos marcos normativos. Para obtener más información, consulte Controles de Amazon API Gateway en la Guía del usuario de AWS Security Hub.
Registro de ejecución estándar
Al habilitar el registro de ejecución en una etapa, API Gateway crea y administra automáticamente un grupo de registros de Registros de CloudWatch. El nombre del grupo de registro es API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}. Dentro de cada grupo de registro, los registros se dividen en flujos de registros ordenados por la hora del último evento.
Con el registro de ejecución estándar:
-
Los eventos de registro se truncan a 1 KB.
-
API Gateway administra el nombre del grupo de registro. No puede elegir el nombre del grupo de registro ni enviar registros directamente a Amazon S3 o Firehose.
Para habilitar el registro de ejecución estándar, establezca el loggingLevel en la etapa como ERROR o INFO. No se necesitan más configuraciones.
Permisos
Para habilitar CloudWatch Logs, debe conceder permiso a API Gateway para leer y escribir registros en CloudWatch para su cuenta. La política administrada AmazonAPIGatewayPushToCloudWatchLogs cuenta con todos los permisos necesarios.
Cree un rol de IAM con apigateway.amazonaws.com como entidad de confianza, asocie la política anterior y establezca el ARN del rol de IAM en la propiedad cloudWatchRoleArn de la cuenta. Debe establecer esta propiedad de forma independiente para cada región de AWS en la que desee habilitar Registros de CloudWatch.
nota
API Gateway llama a AWS Security Token Service para asumir el rol de IAM, por lo que debe asegurarse de que AWS STS esté habilitado para la región. Para obtener más información, consulte Administración de AWS STS en una región de AWS.
Habilitación del registro de ejecución (consola)
Antes de empezar, implemente la API en una etapa y configure un ARN de rol de Registros de CloudWatch adecuado para la cuenta.
Inicie sesión en la consola de API Gateway, en https://console.aws.amazon.com/apigateway
. -
En el panel de navegación principal, elija Configuración y, a continuación, en Registro, elija Editar.
-
En ARN de rol de registro de CloudWatch, ingrese el ARN de un rol de IAM con los permisos adecuados. Tendrá que hacer esto una vez para cada una de las Cuenta de AWS que creen API mediante API Gateway.
-
En el panel de navegación principal, elija API, elija la API de REST y, a continuación, elija Etapas.
-
Elija una etapa y, a continuación, en la sección Registros y rastreo, elija Editar.
-
Elija un nivel de registro en el menú desplegable Registros de CloudWatch:
-
Desactivado: API Gateway no registra las solicitudes de esta etapa.
-
Solo errores: API Gateway solo registra los errores.
-
Errores y registros de información: API Gateway registra todos los eventos.
-
-
(Opcional) Seleccione el seguimiento de datos para registrar todos los datos de solicitud y respuesta. Esto puede dar como resultado el registro de información confidencial.
nota
Le recomendamos que no utilice Rastreo de datos para las API de producción.
-
(Opcional) Seleccione Métricas detalladas para activar las métricas detalladas de CloudWatch. Para obtener más información, consulte Supervisión de la ejecución de la API de REST con métricas de Amazon CloudWatch.
-
Elija Save changes (Guardar cambios).
No es necesario volver a implementar la API cuando se actualiza la configuración de la etapa.
Habilitación del registro de ejecución (CloudFormation)
Utilice la propiedad MethodSettings del recurso de etapa para habilitar el registro de la ejecución.
TestStage: Type: AWS::ApiGateway::Stage Properties: StageName: test RestApiId: !Ref MyAPI DeploymentId: !Ref Deployment MethodSettings: - ResourcePath: "/*" HttpMethod: "*" LoggingLevel: INFO
Para habilitar CloudWatch Logs, debe conceder permiso a API Gateway para leer y escribir registros en CloudWatch para su cuenta. Para obtener más información, consulte Asociar una cuenta a un rol de IAM en la Guía del usuario de AWS CloudFormation.
Entrega de Registros de Amazon CloudWatch para los registros de ejecución
La entrega de Registros de Amazon CloudWatch proporciona una ruta alternativa para los registros de ejecución. En lugar de escribir en un grupo de registro administrado por API Gateway, configure una entrega que envíe los registros de ejecución a los destinos que usted posee y controla.
Con la entrega de Registros de Amazon CloudWatch:
-
Los eventos de registro pueden ocupar hasta 1 MB, lo que permite capturar datos de solicitud y respuesta más completos. Las cargas útiles que superan 1 MB siguen truncadas.
-
Se elige el destino: los grupos de registro de Registros de CloudWatch propios, buckets de Amazon S3 o transmisiones de Firehose.
-
Puede enviar registros a varios destinos simultáneamente.
-
Se controla la configuración del grupo de registro, incluidos los nombres y la retención.
importante
La entrega de Registros de CloudWatch sustituye al registro de ejecución estándar. Al configurar una entrega, API Gateway deja de escribir en el grupo de registro administrado automáticamente. No puede usar ambas rutas al mismo tiempo para la misma etapa.
Al crear una entrega, API Gateway dirige los registros de ejecución a los destinos configurados en lugar de al grupo de registro administrado automáticamente. Al eliminar una entrega, los registros de ejecución vuelven a fluir automáticamente al grupo de registro administrado automáticamente. No es necesario realizar cambios en la configuración de API Gateway más allá del requisito previo de configurar loggingLevel en ERROR o INFO.
nota
La entrega de registros se realiza bajo un modelo de mejor esfuerzo. En casos excepcionales, es posible que algunos eventos de registro no se entreguen.
aviso
Antes de habilitar la entrega de registros, actualice los paneles, las alarmas o los filtros de suscripción que hagan referencia al grupo de registro administrado automáticamente (API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}). Una vez que se activa la entrega, ese grupo de registro ya no recibe nuevos eventos.
En la siguiente tabla, se compara el registro de ejecución estándar con la entrega de Registros de Amazon CloudWatch.
| Registro de ejecución estándar | Entrega de Registros de Amazon CloudWatch | |
|---|---|---|
| Tamaño máximo del evento de registro | 1 KB | 1 MB |
| Destinos | Registros de CloudWatch (grupo de registro administrado) | Registros de CloudWatch, Amazon S3, Firehose (los recursos propios) |
| Múltiples destinos | No | Sí |
| Nombre de grupo de registro | Corregido por API Gateway | Se elige |
| Configuración | automática cuando el registro está habilitado | Requiere crear una entrega de Registros de Amazon CloudWatch |
| Requisito previo | Establezca loggingLevel en ERROR o INFO |
Establezca loggingLevel en ERROR o INFO |
nota
Si configura loggingLevel en OFF después de configurar una entrega, no se generará ni entregará ningún registro de ejecución. Los destinos de entrega permanecen configurados, pero no reciben datos.
Para crear una entrega, consulte Creación de una entrega de registros para los registros de ejecución de la API de REST.
