Uso do CloudWatch para monitorar e registrar dados da API GraphQL

Você pode registrar e depurar sua API GraphQL usando métricas e logs do CloudWatch. Essas ferramentas permitem que os desenvolvedores monitorem o desempenho, solucionem problemas e otimizem suas operações do GraphQL de forma eficaz.

Métricas do CloudWatch é uma ferramenta que fornece uma ampla variedade de métricas para monitorar o desempenho e o uso da API. Essas métricas são classificadas em categorias principais:

O guia também apresenta as métricas aprimoradas, que oferecem dados mais granulares sobre desempenho do resolvedor, interações com fontes de dados e operações individuais do GraphQL. Essas métricas fornecem insights mais profundos, mas têm custos adicionais.

CloudWatch Logs é uma ferramenta que habilita recursos de log para suas APIs GraphQL. Os logs podem ser definidos em dois níveis da API:

Você pode configurar o log, interpretar as entradas e usar os dados do log para solução de problemas e otimização. O AWS AppSync fornece vários tipos de log que revelam os dados de execução, análise, validação e resolução de campo da consulta.

Definição e configuração

Para ativar o registro automático em uma API GraphQL, use o console do AWS AppSync.

Configuração de perfil do IAM manual

Se você optar por usar um perfil do IAM existente, a função deverá conceder ao AWS AppSync as permissões necessárias para gravar logs no CloudWatch. Para configurar isso, é necessário fornecer um ARN do perfil de serviço para que o AWS AppSync possa assumir esse perfil ao gravar os logs.

No console do IAM, crie uma nova política com o nome AWSAppSyncPushToCloudWatchLogsPolicy que tenha a seguinte definição:

JSON

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

Em seguida, crie um novo perfil com o nome AWSAppSyncPushToCloudWatchLogsRole e anexe a política acima para essa função. Edite a relação de confiança desse perfil da seguinte forma:

JSON

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

Copie o ARN do perfil e use-o ao configurar o registro em uma API GraphQL do AWS AppSync.

métricas do CloudWatch

Você pode usar as métricas do CloudWatch para monitorar e fornecer alertas sobre eventos específicos que podem resultar em códigos de status HTTP ou em latência. As seguintes métricas são emitidas:

Assinaturas em tempo real

Todas as métricas são emitidas em uma dimensão: GraphQLAPIId. Isso significa que todas as métricas são acopladas com IDs de API do GraphQL. As seguintes métricas estão relacionadas às assinaturas do GraphQL em WebSockets puros:

Comparar mensagens de entrada e de saída

Quando uma mutação é executada, os campos de assinatura com a diretiva @aws_subscribe para essa mutação são invocados. Cada invocação de assinatura gera uma mensagem de entrada. Por exemplo, se dois campos de assinatura especificarem a mesma mutação em @aws_subscribe, duas mensagens de entrada serão geradas quando essa mutação for chamada.

Uma mensagem de saída equivale a 5 kB de dados entregues aos clientes do WebSocket. Por exemplo, enviar 15 kB de dados para 10 clientes gera 30 mensagens de saída (15 kB * 10 clientes/5 kB por mensagem = 30 mensagens).

É possível solicitar aumentos de cota para mensagens de entrada ou de saída. Para obter mais informações, consulte Endpoints e cotas do AWS AppSync no guia Referência geral da AWS e as instruções de Solicitação de aumento de cota no Guia do usuário sobre Service Quotas.

Métricas aprimoradas

As métricas aprimoradas emitem dados granulares sobre o uso e o desempenho da API, como contagens de solicitações e erros do AWS AppSync, latência e acertos/erros do cache. Todos os dados de métricas aprimoradas são enviados para sua conta do CloudWatch, e você pode configurar os tipos de dados que serão enviados.

Essas métricas podem ser encontradas em várias páginas de configurações no console do AWS AppSync. Na página de configurações da API, a seção Métricas aprimoradas permite ativar ou desativar os seguintes itens:

Comportamento das métricas de resolvedores: essas opções controlam como métricas adicionais para resolvedores são coletadas. Você pode optar por ativar as métricas de resolvedores de solicitações completas (métricas ativadas para todos os resolvedores de solicitações) ou métricas para cada resolvedor (métricas ativadas somente para resolvedores em que a configuração está definida como ativada). As seguintes opções estão disponíveis:

Comportamento das métricas de fontes de dados: essas opções controlam como métricas adicionais para fontes de dados são coletadas. Você pode optar por ativar as métricas de fontes de dados de solicitações completas (métricas ativadas para todas as fontes de dados de solicitações) ou as métricas para cada fonte de dados (métricas ativadas somente para as fontes de dados em que a configuração está definida como ativada). As seguintes opções estão disponíveis:

Métricas de operação: ativa métricas em nível operacional do GraphQL.

CloudWatch logs

Você pode configurar dois tipos de registro em log em qualquer API GraphQL nova ou existente: nível de solicitação e nível de campo.

Logs a nível de solicitação

Quando o registro em log a nível de solicitação (Incluir conteúdo detalhado) é configurado, as seguintes informações são registradas em log:

Logs a nível de campo

Quando o registro log a nível de campo é configurado, as seguintes informações são registradas em log:

Se você ativar o registro, o AWS AppSync gerencia o CloudWatch Logs. O processo inclui a criação de grupos de log e fluxos de log, além de relatórios aos fluxos de log com esses logs.

Ao ativar o registro em log em uma API GraphQL e fazer solicitações, o AWS AppSync cria um grupo de logs e registra os fluxos no grupo de logs. O grupo de logs é chamado seguindo o formato /aws/appsync/apis/{graphql_api_id}. Dentro de cada grupo de logs, os logs são subdivididos em fluxos de log. Esses são ordenados por Hora do último evento conforme os dados registrados em log são reportados.

Cada evento de log é marcado com o x-amzn-RequestId dessa solicitação. Isso ajuda você a filtrar os eventos de log no CloudWatch para obter todas as informações registradas em log relativas a essa solicitação. Você pode obter o RequestId dos cabeçalhos da resposta de cada solicitação do AWS AppSync do GraphQL.

O registro em log a nível de campo é configurado com os seguintes níveis de log:

Benefícios do monitoramento

É possível usar o registro em log e as métricas para identificar, solucionar problemas e otimizar as consultas do GraphQL. Por exemplo, isso ajudará a depurar problemas de latência usando as informações de rastreamento registradas em log para cada campo na consulta. Para demonstrar isso, suponha que você está usando um ou mais resolvedores aninhados em uma consulta do GraphQL. Um exemplo de operação de campo no CloudWatch Logs pode ser semelhante ao seguinte:

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

Isso pode corresponder a um esquema do GraphQL, semelhante ao seguinte:

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

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

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

Nos resultados do log acima, o path mostra um único item nos dados retornados da execução de uma consulta chamada singlePost(). Nesse exemplo, ele representa o campo nome no primeiro índice (0). O startOffset fornece um desvio do início da operação da consulta do GraphQL. A duração é o tempo total para resolver o campo. Esses valores podem ser úteis para entender por que os dados de uma fonte de dados particular podem estar com execução mais lenta que o esperado, ou se um campo específico está atrasando toda a consulta. Por exemplo, é possível aumentar um throughput provisionado para uma tabela do Amazon DynamoDB ou remover um campo específico de uma consulta que está fazendo com que a execução global tenha um desempenho insatisfatório.

A partir de 8 de maio de 2019, o AWS AppSync gera eventos de log como JSON totalmente estruturado. Isso pode ajudar você a usar serviços de análise de log, como o CloudWatch Logs Insights e o Amazon OpenSearch Service, para compreender o desempenho das solicitações do GraphQL e as características de uso dos campos de esquema. Por exemplo, é possível identificar facilmente resolvedores com grandes latências que podem ser a causa raiz de um problema de desempenho. Também é possível identificar os campos mais e menos usados no esquema e avaliar o impacto de desativar campos do GraphQL.

Detecção de conflitos e registro em log de sincronização

Se uma API do AWS AppSync tiver o registro em log no CloudWatch Logs configurado com o Nível de log do resolvedor de campo definido como Tudo, o AWS AppSync emitirá informações de detecção e resolução de conflitos para o grupo de logs. Isso fornece um insight granular de como a API do AWS AppSync respondeu a um conflito. Para ajudar você a interpretar a resposta, as seguintes informações são fornecidas nos logs:

Usar contagens de tokens para otimizar suas solicitações

As solicitações que consomem menos ou igual a 1.500 KB por segundo de memória e tempo de vCPU recebem um token. As solicitações com consumo de recursos superior a 1.500 KB por segundo recebem tokens adicionais. Por exemplo, se uma solicitação consumir 3.350 KB por segundo, o AWS AppSync aloca três tokens (arredondados para o próximo valor inteiro) à solicitação. Por padrão, o AWS AppSync aloca no máximo 5.000 ou 10.000 tokens de solicitação por segundo para as APIs da sua conta, dependendo da região da AWS em que é exibida. Se cada uma das suas APIs usar uma média de dois tokens por segundo, você terá o limite de 2.500 ou 5.000 solicitações por segundo, respectivamente. Se você precisar de mais tokens por segundo do que o valor alocado, poderá enviar uma solicitação para aumentar a cota padrão da taxa de tokens de solicitação. Para obter mais informações, consulte Endpoints e cotas do AWS AppSync Guia do Referência geral da AWS e Solicitar um aumento da cota no Guia do usuário do Service Quotas.

Uma alta contagem de tokens por solicitação pode indicar que há uma oportunidade de otimizar suas solicitações e melhorar o desempenho da sua API. Os fatores que podem aumentar sua contagem de tokens por solicitação incluem:

Limites de tamanho de log

Por padrão, se o registro em log estiver ativado, o AWS AppSync enviará até 1 MB de logs por solicitação. Logs que excederem esse tamanho serão truncados. Para reduzir tamanhos de log, escolha o nível de registro em log de ERROR para logs em nível de campo e desative o registro em log de VERBOSE, ou desative totalmente os logs em nível de campo se não forem necessários. Como alternativa ao nível de log de ALL, você pode usar métricas aprimoradas para obter métricas de resolvedores, fontes de dados ou operações do GraphQL específicos, ou usar os utilitários de registro em log fornecidos pelo AppSync para registrar somente as informações necessárias.

Referência de tipo de log

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"
}

Rastreamento

{
    "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"
}

Analisar logs com o CloudWatch Logs Insights

Veja a seguir exemplos de consultas que você pode executar para obter insights práticos sobre o desempenho e a integridade das operações do GraphQL. Esses exemplos estão disponíveis como consultas de exemplo no console do CloudWatch Logs Insights. No console do CloudWatch, escolha Logs Insights, selecione o grupo de logs do AWS AppSync para sua API GraphQL e escolha consultas do AWS AppSync em Consultas de exemplo.

A consulta a seguir retorna as 10 principais solicitações do GraphQL com o máximo de tokens consumidos:

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

A consulta a seguir retorna os 10 principais resolvedores com latência máxima:

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

A consulta a seguir retorna os resolvedores invocados com mais frequência:

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

A consulta a seguir retorna resolvedores com a maioria dos erros em modelos de mapeamento:

  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

A consulta a seguir retorna estatísticas de latência do resolvedor:

  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

A consulta a seguir retorna estatísticas de latência de 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

Os resultados das consultas do CloudWatch Logs Insights podem ser exportados para painéis do CloudWatch.

Analisar seus registros com o OpenSearch Service

É possível pesquisar, analisar e visualizar seus logs do AWS AppSync com o Amazon OpenSearch Service para identificar gargalos de desempenho e as causas raiz de problemas operacionais. É possível identificar resolvedores com a latência máxima e os erros. Além disso, você pode usar Painéis do OpenSearch para criar painéis com visualizações avançadas. Os Painéis do OpenSearch é uma ferramenta de visualização e exploração de dados de código aberto disponível no OpenSearch Service. Com os Painéis do OpenSearch, é possível monitorar continuamente o desempenho e a integridade das operações do GraphQL. Por exemplo, você pode criar painéis para visualizar a latência P90 das solicitações do GraphQL e analisar as latências P90 de cada resolvedor.

Ao usar o OpenSearch Service, use “cwl*” como padrão de filtro para pesquisar índices do OpenSearch. O OpenSearch Service indexa os logs transmitidos do CloudWatch Logs com um prefixo "cwl-". Para diferenciar logs da API do AWS AppSync de outros logs do CloudWatch enviados para o OpenSearch Service, recomendamos adicionar uma expressão de filtro adicional de graphQLAPIID.keyword=YourGraphQLAPIID à sua pesquisa.

Migração do formato de log

Os eventos de log gerados pelo AWS AppSync em 8 de maio de 2019 ou posterior são formatados como JSON totalmente estruturado. Para analisar solicitações do GraphQL antes de 8 de maio de 2019, poderá migrar logs mais antigos para JSON totalmente estruturado usando um script disponível no Exemplo do GitHub. Se for necessário usar o formato de log antes de 8 de maio de 2019, crie um tíquete de suporte com as seguintes configurações: defina Tipo como Gerenciamento de contas e, depois, defina Categoria como Pergunta geral sobre a conta.

Você também pode usar filtros de métrica no CloudWatch para transformar os dados de log em métricas numéricas do CloudWatch, que podem ser usadas para criar um gráfico ou definir um alarme.