# Registro de ejecución para API de REST
<a name="rest-api-execution-logging"></a>

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](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) en la *Guía del usuario de AWS Security Hub*.

## Registro de ejecución estándar
<a name="rest-api-execution-logging-standard"></a>

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
<a name="rest-api-execution-logging-permissions"></a>

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](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAPIGatewayPushToCloudWatchLogs.html) 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](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html#cloudWatchRoleArn) de la [cuenta](https://docs.aws.amazon.com/apigateway/latest/api/API_GetAccount.html). 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html).

### Habilitación del registro de ejecución (consola)
<a name="rest-api-execution-logging-console"></a>

Antes de empezar, implemente la API en una etapa y configure un ARN de rol de Registros de CloudWatch adecuado para la cuenta.

1. Inicie sesión en la consola de API Gateway, en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).

1. En el panel de navegación principal, elija **Configuración** y, a continuación, en **Registro**, elija **Editar**.

1. 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.

1. En el panel de navegación principal, elija **API**, elija la API de REST y, a continuación, elija **Etapas**.

1. Elija una etapa y, a continuación, en la sección **Registros y rastreo**, elija **Editar**.

1. 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.

1. (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.

1. (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](monitoring-cloudwatch.md).

1. 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)
<a name="rest-api-execution-logging-cfn"></a>

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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-account.html#aws-resource-apigateway-account--examples) en la *Guía del usuario de AWS CloudFormation*.

## Entrega de Registros de Amazon CloudWatch para los registros de ejecución
<a name="rest-api-execution-logging-delivery"></a>

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](rest-api-create-log-delivery.md).