As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Usando CloudWatch para monitorar e registrar dados da API GraphQL

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

CloudWatch metrics é 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 registro para seu GraphQL APIs. Os logs podem ser definidos em dois níveis da API:

Você pode configurar o registro, interpretar as entradas do registro e usar os dados do registro para solução de problemas e otimizaçã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 AWS AppSync console.

Configuração de perfil do IAM manual

Se você optar por usar uma função do IAM existente, a função deverá conceder AWS AppSync as permissões necessárias para gravar registros CloudWatch. Para configurar isso manualmente, você deve fornecer um ARN da função de serviço para que AWS AppSync possa assumir a função ao gravar os registros.

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

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

Em seguida, crie uma nova função com o nome AWSAppSyncPushToCloudWatchLogsRolee anexe a política recém-criada à função. Edite a relação de confiança desse perfil da seguinte forma:

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

Copie o ARN da função e use-o ao configurar o registro para uma API GraphQL AWS AppSync .

CloudWatch métricas

Você pode usar CloudWatch métricas 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: gráfico QLAPIId. Isso significa que todas as métricas são acopladas à API IDs GraphQL. As métricas a seguir estão relacionadas às assinaturas do GraphQL em vez das puras: WebSockets

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. 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 métricos aprimorados são enviados para sua CloudWatch conta, 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 AWS AppSync console. 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 troncos

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, AWS AppSync gerencia os CloudWatch registros. 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.

Quando você ativa o registro em uma API do GraphQL e faz solicitações, AWS AppSync cria um grupo de registros e fluxos de registros sob o grupo de registros. 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 eventos de registro CloudWatch para obter todas as informações registradas sobre essa solicitação. Você pode obter o dos cabeçalhos RequestId de resposta de cada solicitação do AWS AppSync 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, AWS AppSync gera eventos de log como JSON totalmente estruturado. Isso pode ajudar você a usar serviços de análise de log, como CloudWatch Logs Insights e Amazon OpenSearch Service, para entender o desempenho de suas solicitações do GraphQL e as características de uso de seus 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 AWS AppSync API tiver o registro em CloudWatch registros configurado com o nível de registro do resolvedor de campo definido como Todos, ela AWS AppSync emitirá informações de detecção e resolução de conflitos para o grupo de registros. Isso fornece uma visão granular de como a AWS AppSync API 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, AWS AppSync aloca três tokens (arredondados para o próximo valor inteiro) para a solicitação. Por padrão, AWS AppSync aloca um máximo de 5.000 ou 10.000 tokens de solicitação por segundo APIs na sua conta, dependendo da AWS região em que está implantado. Se APIs cada um usar uma média de dois tokens por segundo, você estará limitado a 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 AWS AppSync endpoints e cotas no Referência geral da AWS guia e Solicitando um aumento de cota no Service Quotas User Guide.

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 estiver ativado, AWS AppSync enviará até 1 MB de registros 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 ALL log, você pode usar métricas aprimoradas para obter métricas sobre resolvedores, fontes de dados ou operações do GraphQL específicos, ou utilizar os utilitários de registro fornecidos AppSync por 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"
}

Analisando seus registros 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 exemplos de consultas no console do CloudWatch Logs Insights. No CloudWatchconsole, escolha Logs Insights, selecione o AWS AppSync grupo de registros para sua API GraphQL e, em seguida, escolha AWS AppSync consultas em Exemplos de consultas.

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 CloudWatch painéis.

Analise seus registros com o OpenSearch Service

Você pode pesquisar, analisar e visualizar seus AWS AppSync registros com o Amazon OpenSearch Service para identificar gargalos de desempenho e causas-raiz de problemas operacionais. É possível identificar resolvedores com a latência máxima e os erros. Além disso, você pode usar OpenSearch painéis para criar painéis com visualizações poderosas. OpenSearch O Dashboards é uma ferramenta de visualização e exploração de dados de código aberto disponível no OpenSearch Service. Usando OpenSearch painéis, você pode monitorar continuamente o desempenho e a integridade de suas 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 OpenSearch Service, use “cwl*” como padrão de filtro para pesquisar OpenSearch índices. OpenSearch O serviço indexa os registros transmitidos do CloudWatch Logs com o prefixo “cwl -”. Para diferenciar os registros da AWS AppSync API de outros CloudWatch registros enviados ao OpenSearch Serviço, recomendamos adicionar uma expressão de filtro adicional de graphQLAPIID.keyword=YourGraphQLAPIID à sua pesquisa.

Migração do formato de log

Os eventos de registro AWS AppSync gerados em ou após 8 de maio de 2019 são formatados como JSON totalmente estruturado. Para analisar solicitações do GraphQL anteriores a 8 de maio de 2019, você pode migrar registros antigos para um JSON totalmente estruturado usando um script disponível na amostra. 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 métricos CloudWatch para transformar dados de registro em CloudWatch métricas numéricas, para que você possa representar graficamente ou definir um alarme para eles.