Uso de CloudWatch para supervisar y registrar los datos de la API de GraphQL

Puede registrar y depurar su API de GraphQL mediante métricas y registros de CloudWatch. Estas herramientas permiten a los desarrolladores supervisar el rendimiento, solucionar problemas y optimizar sus operaciones de GraphQL de forma eficaz.

Las métricas de CloudWatch son una herramienta que proporciona una amplia gama de métricas para supervisar el rendimiento y el uso de las API. Estas métricas se dividen en las siguientes dos categorías principales:

En la guía también se presentan las métricas mejoradas, que ofrecen datos más detallados sobre el rendimiento de los solucionadores, las interacciones entre los orígenes de datos y las operaciones individuales de GraphQL. Estas métricas proporcionan información más detallada, pero conllevan costes adicionales.

Registros de CloudWatch es una herramienta que habilita las capacidades de registro para las API de GraphQL. Los registros se pueden configurar en dos niveles de la API:

Puede configurar registros, interpretar las entradas de registro y utilizar los datos de registro para la solución de problemas y la optimización. AWS AppSync proporciona varios tipos de registro que muestran los datos de ejecución, análisis, validación y resolución de campo de su consulta.

Ajustes y configuración

Para activar el registro automático en una API de GraphQL, use la consola de AWS AppSync.

Configuración manual del rol de IAM

Si decide utilizar un rol de IAM existente, la función debe conceder a AWS AppSync los permisos necesarios para escribir registros en CloudWatch. Para configurarlo manualmente, debe proporcionar un ARN del rol de servicio para que AWS AppSync pueda asumir este rol al escribir los registros.

En la consola de IAM, cree una nueva política con el nombre AWSAppSyncPushToCloudWatchLogsPolicy que tenga la siguiente definición:

JSON

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

A continuación, cree un nuevo rol con el nombre AWSAppSyncPushToCloudWatchLogsRole y adjunte la política recién creada a este rol. Edite la relación de confianza para este rol de la siguiente manera:

JSON

{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
        "Effect": "Allow",
        "Principal": {
            "Service": "appsync.amazonaws.com"
        },
        "Action": "sts:AssumeRole"
        }
    ]
}

Copie el ARN del rol y utilícelo al configurar el registro para una API de GraphQL de AWS AppSync.

Métricas de CloudWatch

Puede utilizar las métricas de CloudWatch para supervisar y enviar alertas sobre eventos específicos que pueden provocar códigos de estado HTTP o de latencia. Se emiten las siguientes métricas:

Suscripciones en tiempo real

Todas las métricas se emiten en una dimensión: GraphQLAPIId. Esto significa que todas las métricas están vinculadas a los ID de la API de GraphQL. Las siguientes métricas están relacionadas con suscripciones de GraphQL puramente a través de WebSockets:

Comparación de los mensajes entrantes y salientes

Cuando se ejecuta una mutación, se invocan campos de suscripción con la directiva @aws_subscribe para esa mutación. Cada invocación de suscripción genera un mensaje entrante. Por ejemplo, si dos campos de suscripción especifican la misma mutación en @aws_subscribe, se generarán dos mensajes entrantes cuando se llame a esa mutación.

Un mensaje saliente equivale a 5 kB de datos entregados a clientes de WebSocket. Por ejemplo, el envío de 15 kB de datos a 10 clientes da como resultado 30 mensajes salientes (15 kB * 10 clientes / 5 kB por mensaje = 30 mensajes).

Puede solicitar aumentos de cuota para mensajes entrantes o salientes. Para obtener más información, consulte Puntos de conexión y cuotas de AWS AppSync en la Guía de referencia general de AWS y las instrucciones sobre Cómo solicitar un aumento de cuota en la Guía del usuario de Service Quotas.

Métricas mejoradas

Las métricas mejoradas emiten datos detallados sobre el uso y el rendimiento de la API, como el recuento de solicitudes y errores de AWS AppSync, la latencia y los aciertos o errores de caché. Todos los datos de métricas mejoradas se envían a su cuenta de CloudWatch, y es posible configurar los tipos de datos que se enviarán.

Estas métricas se pueden encontrar en varias páginas de configuración de la consola de AWS AppSync. En la página de configuración de la API, la sección Métricas mejoradas le permite activar o desactivar los siguientes elementos:

Comportamiento de las métricas de los solucionadores: estas opciones controlan la forma en que se recopilan las métricas adicionales de los solucionadores. Puede optar por habilitar las métricas de los solucionadores de solicitudes completas (las métricas están habilitadas para todos los solucionadores en las solicitudes), o bien las métricas por solucionador (las métricas solo están habilitadas para los solucionadores cuya configuración esté habilitada). Están disponibles las siguientes opciones:

Comportamiento de las métricas de los orígenes de datos: estas opciones controlan la forma en que se recopilan las métricas adicionales de los orígenes de datos. Puede optar por habilitar las métricas de los orígenes de datos de solicitudes completas (las métricas están habilitadas para todos los orígenes de datos en las solicitudes), o bien las métricas por origen de datos (las métricas solo están habilitadas para los orígenes de datos cuya configuración esté habilitada). Están disponibles las siguientes opciones:

Métricas de operación: habilita métricas a nivel de operación de GraphQL.

Registros de CloudWatch

Puede configurar dos tipos de registros en cada API de GraphQL nueva o existente, tanto en el nivel del campo como de la solicitud.

Registros en el nivel de la solicitud

Cuando se configura el registro en el nivel de solicitud (Incluir el contenido excesivamente detallado), se registra la información siguiente:

Registros en el nivel del campo

Cuando se configura el registro a nivel de campo, se registra la información siguiente:

Si activa el registro, AWS AppSync administra los Registros de CloudWatch. El proceso incluye la creación de grupos y flujos de registros, y la notificación a los flujos de registro con dichos registros.

Al habilitar el registro en una API de GraphQL y hacer solicitudes, AWS AppSync crea un grupo de registros y flujos de registros en el grupo de registros. Al grupo de registro se le asigna un nombre con el formato /aws/appsync/apis/{graphql_api_id}. Dentro de cada grupo, los registros se dividen en flujos de registros. Estos se ordenan en función de la Last Event Time (Hora del último evento) según los datos registrados.

Cada evento de registro se etiqueta con el x-amzn-RequestId de dicha solicitud. Esto le ayuda a filtrar los eventos de registro en CloudWatch para obtener toda la información registrada acerca de dicha solicitud. Puede obtener el RequestId de los encabezados de la respuesta de cada solicitud de GraphQL de AWS AppSync.

El registro en el nivel del campo se configura con los siguientes niveles de registro:

Ventajas de la supervisión

Puede utilizar el registro y las métricas para identificar, solucionar problemas y optimizar sus consultas de GraphQL. Por ejemplo, le pueden ayudar a depurar problemas de latencia mediante la información de seguimiento registrada para cada campo en la consulta. Para ver una demostración, suponga que utiliza uno o varios solucionadores anidados en una consulta de GraphQL. Una operación de campo de muestra en Registros de CloudWatch podría tener un aspecto similar al siguiente:

{
    "path": [
        "singlePost",
        "authors",
        0,
        "name"
    ],
    "parentType": "Post",
    "returnType": "String!",
    "fieldName": "name",
    "startOffset": 416563350,
    "duration": 11247
}

Esto podría equivaler a un esquema de GraphQL, similar al siguiente:

type Post {
  id: ID!
  name: String!
  authors: [Author]
}

type Author {
  id: ID!
  name: String!
}

type Query {
  singlePost(id:ID!): Post
}

En los resultados del registro anterior, path muestra un solo elemento en los datos devueltos al ejecutar una consulta denominada singlePost(). En este ejemplo, representa el campo name en el primer índice (0). El valor de startOffset proporciona una demora desde el inicio de la operación de consulta de GraphQL. El valor de duration es el tiempo total necesario para resolver el campo. Estos valores pueden ser útiles para solucionar problemas relacionados con el motivo por el que un determinado origen de datos puede ejecutarse más lentamente de lo esperado, o si un campo específico está ralentizando toda la consulta. Por ejemplo, puede elegir aumentar el rendimiento aprovisionado de una tabla de Amazon DynamoDB o quitar un campo específico de una consulta que provoca que la ejecución vaya más lenta en general.

Desde el 8 de mayo de 2019, AWS AppSync genera eventos de registro como archivos JSON completamente estructurados. Esto le permite utilizar los servicios de análisis de registros como CloudWatch Logs Insights y Amazon OpenSearch Service para comprender el rendimiento de sus solicitudes de GraphQL y el uso de las características de los campos de esquema. Por ejemplo, podrá identificar fácilmente solucionadores con latencias elevadas que podrían ser la causa de un problema de rendimiento. También podrá identificar los campos utilizados con mayor y menor frecuencia en su esquema y evaluar el impacto de dejar de usar campos de GraphQL.

Detección de conflictos y registro de sincronización

Si una API de AWS AppSync tiene el registro en CloudWatch Logs configurado con el nivel de registro del solucionador de campo establecido en Todo, AWS AppSync emite información de detección y resolución de conflictos al grupo de registro. Esto proporciona información detallada sobre cómo respondió la API de AWS AppSync a un conflicto. Para ayudarle a interpretar la respuesta, en los registros se proporciona la información siguiente:

Uso del recuento de tókenes para optimizar sus solicitudes

A las solicitudes que utilizan 1500 KB/s de memoria y tiempo de vCPU o menos se les asigna un token. Las solicitudes con un consumo de recursos superior a 1500 KB/s se les asignan más tókenes. Por ejemplo, si una solicitud consume 3350 KB/s, AWS AppSync asigna tres tókenes (redondeados al siguiente valor entero) a la solicitud. De forma predeterminada, AWS AppSync asigna un máximo de 5000 o 10 000 tókenes de solicitud por segundo a las API de su cuenta, en función de la Región de AWS en la que se haya implementado. Si cada una de sus API usa un promedio de dos tókenes por segundo, tendrá un límite de 2500 o 5000 solicitudes por segundo, respectivamente. Si necesita más tókenes por segundo de lo que se le han asignado, puede enviar una solicitud para aumentar la cuota predeterminada de tókenes de solicitud. Para obtener más información, consulte Puntos de conexión y cuotas de AWS AppSync en la Guía de Referencia general de AWS y Solicitar un aumento de cuota en la Guía del usuario de Service Quotas.

Un número elevado de tókenes por solicitud podría indicar que existe la posibilidad de optimizar tus solicitudes y mejorar el rendimiento de su API. Entre los factores que pueden aumentar el número de tókenes por solicitud se incluyen los siguientes:

Límites de tamaño de registros

De forma predeterminada, si se ha activado la creación de registros, AWS AppSync enviará hasta 1 MB de registros por solicitud. Los registros que superen este tamaño se truncarán. Para reducir el tamaño de los registros, elija el nivel de registro ERROR para los registros a nivel de campo y deshabilite el registro VERBOSE, o bien deshabilite por completo los registros a nivel de campo si no es necesario. Como alternativa al nivel de registro ALL, puede usar métricas mejoradas para obtener métricas sobre solucionadores, operaciones de GraphQL u orígenes de datos específicos, o bien puede usar las utilidades de registro que proporciona AppSync para registrar solo la información necesaria.

Referencia de tipos de registros

RequestSummary

{
     "logType": "RequestSummary",
     "requestId": "dbe87af3-c114-4b32-ae79-8af11f3f96f1",
     "graphQLAPIId": "pmo28inf75eepg63qxq4ekoeg4",
     "statusCode": 200,
     "latency": 242000000
}

ExecutionSummary

{
    "duration": 217406145,
    "logType": "ExecutionSummary",
    "requestId": "dbe87af3-c114-4b32-ae79-8af11f3f96f1",
    "startTime": "2019-01-01T06:06:18.956Z",
    "endTime": "2019-01-01T06:06:19.174Z",
    "parsing": {
        "startOffset": 49033,
        "duration": 34784
    },
    "version": 1,
    "validation": {
        "startOffset": 129048,
        "duration": 69126
    },
    "graphQLAPIId": "pmo28inf75eepg63qxq4ekoeg4"
}

Rastreo

{
    "duration": 216820346,
    "logType": "Tracing",
    "path": [
        "putItem"
    ],
    "fieldName": "putItem",
    "startOffset": 178156,
    "resolverArn": "arn:aws:appsync:us-east-1:111111111111:apis/pmo28inf75eepg63qxq4ekoeg4/types/Mutation/fields/putItem",
    "requestId": "dbe87af3-c114-4b32-ae79-8af11f3f96f1",
    "parentType": "Mutation",
    "returnType": "Item",
    "graphQLAPIId": "pmo28inf75eepg63qxq4ekoeg4"
}

Análisis de sus registros con CloudWatch Logs Insights

A continuación se muestran ejemplos de las consultas que puede ejecutar para obtener datos procesables sobre el rendimiento y el estado de las operaciones de GraphQL. Estos ejemplos están disponibles como solicitudes de ejemplo en la consola de CloudWatch Logs Insights. En la consola de CloudWatch, elija Logs Insights, seleccione el grupo de registro de AWS AppSync de su API de GraphQL y, a continuación, elija consultas de AWS AppSync en Consultas de muestra.

La siguiente consulta devuelve las 10 solicitudes principales de GraphQL con que han usado el número máximo de tókenes:

filter @message like "Tokens Consumed"
| parse @message "* Tokens Consumed: *" as requestId, tokens
| sort tokens desc
| display requestId, tokens
| limit 10

La siguiente consulta devuelve los 10 solucionadores principales con latencia máxima:

  fields resolverArn, duration
| filter logType = "Tracing"
| limit 10
| sort duration desc

La siguiente consulta devuelve los solucionadores invocados con mayor frecuencia:

  fields ispresent(resolverArn) as isRes
| stats count() as invocationCount by resolverArn
| filter isRes and logType = "Tracing"
| limit 10
| sort invocationCount desc

La siguiente consulta devuelve los solucionadores con más errores en el mapeo de plantillas:

  fields ispresent(resolverArn) as isRes
| stats count() as errorCount by resolverArn, logType
| filter isRes and (logType = "RequestMapping" or logType = "ResponseMapping") and fieldInError
| limit 10
| sort errorCount desc

La siguiente consulta devuelve las estadísticas de latencia del solucionador:

  fields ispresent(resolverArn) as isRes
| stats min(duration), max(duration), avg(duration) as avg_dur by resolverArn
| filter isRes and logType = "Tracing"
| limit 10
| sort avg_dur desc

La siguiente consulta devuelve las estadísticas de latencia del campo:

  stats min(duration), max(duration), avg(duration) as avg_dur
  by concat(parentType, '/', fieldName) as fieldKey
| filter logType = "Tracing"
| limit 10
| sort avg_dur desc

Los resultados de las consultas de CloudWatch Logs Insights se pueden exportar a los paneles de CloudWatch.

Análisis de sus registros con OpenSearch Service

Puede buscar, analizar y visualizar sus registros de AWS AppSync con Amazon OpenSearch Service para identificar los cuellos de botella de rendimiento y la causa de origen de los problemas operativos. Puede identificar los solucionadores con los errores y la latencia máxima. Además, puede utilizar Paneles de OpenSearch para crear paneles con visualizaciones muy útiles. Paneles de OpenSearch es una herramienta de exploración y visualización de datos de código abierto disponible en OpenSearch Service. Con los Paneles de OpenSearch, puede supervisar de forma continua el rendimiento y el estado de sus operaciones de GraphQL. Por ejemplo, puede crear paneles que le permitan visualizar la latencia P90 de sus solicitudes de GraphQL y profundizar en las latencias P90 de cada solucionador.

Al utilizar OpenSearch Service, use “cwl*” como el patrón de filtro para las búsquedas en los índices de OpenSearch. OpenSearch Service indexa los registros transmitidos desde CloudWatch Logs con un prefijo de “cwl-”. Para diferenciar los registros de la API de AWS AppSync de otros registros de CloudWatch enviados a OpenSearch Service, le recomendamos agregar una expresión de filtro adicional de graphQLAPIID.keyword=YourGraphQLAPIID a la búsqueda.

Migración del formato de registro

Los eventos de registro generados por AWS AppSync desde el 8 de mayo de 2019 en adelante tienen un formato JSON completamente estructurado. Para analizar las solicitudes de GraphQL anteriores al 8 de mayo de 2019, puede migrar los registros antiguos a archivos JSON completamente estructurados mediante un script disponible en el ejemplo de GitHub. Si necesita utilizar el formato del registro anterior al 8 de mayo de 2019, cree un tique de soporte técnico con la siguiente configuración: establezca Type (Tipo) en Account Management (Administración de cuentas) y, a continuación, establezca Category (Categoría) en General Account Question (Pregunta sobre la cuenta general).

También puede usar filtros de métricas en CloudWatch para convertir los datos de registro en métricas numéricas de CloudWatch que puede representar gráficamente o en las que puede configurar una alarma.