# Configuración del registro de CloudWatch para las API de REST en API Gateway
<a name="set-up-logging"></a>

 Para ayudarle a depurar problemas relacionados con la ejecución de solicitudes o el acceso de clientes a la API, puede habilitar Amazon CloudWatch Logs para registrar las llamadas a la API. Para obtener más información acerca de CloudWatch, consulte [Supervisión de la ejecución de la API de REST con métricas de Amazon CloudWatch](monitoring-cloudwatch.md).

## Formatos de registro de CloudWatch para API Gateway
<a name="apigateway-cloudwatch-log-formats"></a>

 Existen dos tipos de registro de API en CloudWatch: los registros de ejecución y los registros de acceso. En el registro de ejecución, API Gateway administra los CloudWatch Logs. El proceso incluye la creación de grupos y flujos de registros y la notificación a los flujos de registro de las solicitudes y respuestas del intermediario. 

Los datos registrados contienen errores o rastros de ejecución (como cargas o valores de parámetros de solicitud o respuesta) y datos utilizados por los autorizadores de Lambda (que anteriormente se denominaban autorizadores personalizados). Tambien indican si las claves de la API son obligatorias y si los planes de uso están habilitados, y proporcionan otra información. 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*.

Cuando implementa una API, API Gateway crea un grupo de registros y, bajo este, unos flujos de registros. Al grupo de registro se le asigna un nombre con el formato `API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}`. Dentro de cada grupo, los registros se dividen en flujos de registros, que están ordenados en función de la **hora del último evento** de los datos registrados. 

En los registros de acceso, tanto usted como el desarrollador de la API pretenden registrar quién ha obtenido acceso a la API y cómo el intermediario ha obtenido acceso a la API. Puede crear su propio grupo de registros o elegir un grupo de registros existente, que podría administrarse a través de API Gateway. Para especificar los detalles de acceso, se seleccionan variables [`$context`](api-gateway-variables-for-access-logging.md), un formato de registro y un destino de grupo de registro.

El formato del registro de acceso debe incluir al menos `$context.requestId` o `$context.extendedRequestId`. Como práctica recomendada, incluya `$context.requestId` y `$context.extendedRequestId` en el formato de registro.

**`$context.requestId`**  
Esto registra el valor en el encabezado `x-amzn-RequestId`. Los clientes pueden invalidar el valor del encabezado `x-amzn-RequestId` con un valor en formato de identificador único universal (UUID). API Gateway devuelve este ID de solicitud en el encabezado de respuesta `x-amzn-RequestId`. API Gateway sustituye los ID de solicitud invalidados que no tienen el formato de un UUID por `UUID_REPLACED_INVALID_REQUEST_ID` en los registros de acceso.

**`$context.extendedRequestId`**  
ExtendedRequestID es un ID único que API Gateway genera. API Gateway devuelve este ID de solicitud en el encabezado de respuesta `x-amz-apigw-id`. Una persona que llama a la API no puede proporcionar ni anular este ID de solicitud. Es posible que tenga que proporcionar este valor a AWS Support para que le ayude a solucionar los problemas de la API. Para obtener más información, consulte [Variables para el registro de acceso para API Gateway](api-gateway-variables-for-access-logging.md).

Elija un formato de registro que también se utilice en el backend de análisis; por ejemplo, [Common Log Format](https://httpd.apache.org/docs/current/logs.html#common) (CLF), JSON, XML o CSV. Después, puede incluir datos en los registros de acceso para que tengan las métricas calculadas y procesadas. Para definir el formato del registro, establezca el ARN del grupo de registros en la propiedad [accessLogSettings/destinationArn](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#destinationArn) de [stage](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html). Puede obtener el ARN de un grupo de registro en la consola de CloudWatch. Para definir el formato del registro de acceso, establezca el formato elegido en la propiedad [accessLogSetting/format](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#format) de [stage](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html). 

Algunos ejemplos de los formatos de registro de acceso que se utilizan habitualmente se muestran en la consola de API Gateway y se detallan a continuación.
+ `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` (valores separados por comas):

  ```
  $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
  ```

## Permisos de registros de CloudWatch
<a name="set-up-access-logging-permissions"></a>

Para habilitar CloudWatch Logs, debe conceder permiso a API Gateway para leer y escribir registros en CloudWatch para su cuenta. [AmazonAPIGatewayPushToCloudWatchLogs](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAPIGatewayPushToCloudWatchLogs.html) cuenta con todos los permisos necesarios.

**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).

Para conceder estos permisos a la cuenta, cree un rol de IAM con `apigateway.amazonaws.com` como entidad de confianza, asocie a este rol la política anterior y establezca su ARN 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 la propiedad [cloudWatchRoleArn](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html#cloudWatchRoleArn) por separado para cada región de AWS en la que desee habilitar CloudWatch Logs.

Si recibe un error cuando configure el ARN del rol de IAM, verifique la configuración de la cuenta de AWS Security Token Service para asegurarse de que AWS STS esté habilitado en la región que se está utilizando. Para obtener más información acerca de la habilitación de AWS STS, 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#sts-regions-activate-deactivate) en la *Guía del usuario de IAM*.

## Configuración del registro de API de CloudWatch mediante la consola de API Gateway
<a name="set-up-access-logging-using-console"></a>

Para configurar el registro de API de CloudWatch, la API debe estar implementada en una etapa. Además, debe configurarse el ARN de [un rol apropiado de CloudWatch Logs](#set-up-access-logging-permissions) 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 un 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** y, a continuación, realice una de las siguientes acciones:

   1.  Elija una API existente y después una etapa.

   1.  Cree una API e impleméntela como etapa.

1. En el panel de navegación principal, elija **Etapas**.

1.  En la sección **Registros y rastreo**, elija **Editar**.

1. Para habilitar el registro de ejecución:

   1. Elija un nivel de registro en el menú desplegable **Registros de CloudWatch**. A continuación, se muestran los niveles de registro:
      + **Desactivado**: el registro no está activado para esta etapa. 
      + **Solo errores**: el registro solo está habilitado para los errores. 
      + **Registros de errores e información**: el registro está habilitado para todos los eventos.

   1. (Opcional) Seleccione **Rastreo de datos** para activar el registro de rastreo de datos en la etapa. Esto puede ser útil para solucionar problemas de la API, pero puede dar como resultado el registro de datos confidenciales.
**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 acerca de las métricas de CloudWatch, consulte [Supervisión de la ejecución de la API de REST con métricas de Amazon CloudWatch](monitoring-cloudwatch.md).

1. Para habilitar el registro de acceso:

   1. Active el **Registro de acceso personalizado**.

   1. En **ARN del destino de registro de acceso**, ingrese el ARN de un grupo de registro. El formato del ARN es `arn:aws:logs:{region}:{account-id}:log-group:log-group-name`.

   1. En **Formato de registro**, ingrese un formato de registro. Puede elegir **CLF**, **JSON**, **XML** o **CSV**. Para obtener más información sobre ejemplos de formatos de registro, consulte [Formatos de registro de CloudWatch para API Gateway](#apigateway-cloudwatch-log-formats).

1. Seleccione **Save changes (Guardar cambios)**.

**nota**  
Puede habilitar el registro de ejecución y el registro de acceso por separado.

API Gateway ya está listo para registrar solicitudes en la API. Si actualiza la configuración de la etapa, los registros o las variables de la etapa, no necesita volver a implementar la API. 

## Configuración del registro de API de CloudWatch mediante CloudFormation
<a name="set-up-access-logging-using-cloudformation"></a>

Utilice la siguiente plantilla de CloudFormation de ejemplo para crear un grupo de registro de Registros de Amazon CloudWatch y configurar el registro de ejecución y acceso para una etapa. 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*.

```
  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
```