Configuración del registro de CloudWatch para las API de REST en API Gateway

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.

Formatos de registro de CloudWatch para API Gateway

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.

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, 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 $context para modelos de datos, autorizadores, plantillas de mapeo y registro de acceso de CloudWatch.

nota

Solo se admiten las variables $context.

Elija un formato de registro que también se utilice en el backend de análisis; por ejemplo, Common Log Format (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 de stage. 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 de stage.

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):

  $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

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 (con el ARN arn:aws:iam::aws:policy/service-role/AmazonAPIGatewayPushToCloudWatchLogs) tiene todos los permisos necesarios:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:DescribeLogGroups",
                "logs:DescribeLogStreams",
                "logs:PutLogEvents",
                "logs:GetLogEvents",
                "logs:FilterLogEvents"
            ],
            "Resource": "*"
        }
    ]
}

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.

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 de la cuenta. Debe establecer la propiedad 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 en la Guía del usuario de IAM.

Configuración del registro de API de CloudWatch mediante la consola de API Gateway

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 para la cuenta.

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

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

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

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

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

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

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

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

      • Registros completos de solicitudes y respuestas: el registro detallado está habilitado para todos los eventos. Esto puede ser útil para solucionar problemas de la API, pero puede dar como resultado el registro de datos confidenciales.

        nota

        Recomendamos que no utilice Registros completos de solicitudes y respuestas para las API de producción.

   2. Si lo desea, 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.

8. Para habilitar el registro de acceso:

   1. Active el Registro de acceso personalizado.

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

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

9. Elija 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 AWS CloudFormation

Utilice la siguiente plantilla de AWS 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 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