Solução de problemas da API Monitoring

Este guia explica alguns dos problemas que surgem quando você usa a API Monitoring v3.

A API Monitoring faz parte do conjunto de APIs do Cloud. Essas APIs compartilham um conjunto comum de códigos de erro. Para receber uma lista de códigos de erro definidos pelas APIs do Cloud e sugestões gerais sobre como processar os erros, consulte Como processar os erros.

Usar a API Explorer para depuração

A API Explorer é um widget integrado às páginas de referência dos métodos de API. Ela permite que você invoque o método preenchendo campos, sem precisar escrever códigos.

Se você estiver com problemas para invocar um método, use o widget da API Explorer (Try this API) na página de referência desse método para depurar o problema. Consulte a API Explorer para mais informações.

Erros gerais da API

Estes são alguns erros e mensagens da API Monitoring que você pode ver nas suas chamadas de API:

  • 404 NOT_FOUND

    • "O URL solicitado não foi encontrado neste servidor": uma parte do URL está incorreta. Compare o URL com o URL do método, mostrado na página de referência do método. Verifique se há erros de ortografia ("projeto" em vez de "projetos") e problemas de letras maiúsculas ("TimeSeries" em vez de "timeSeries").

    • "projects/PROJECT_ID não é um espaço de trabalho": isso significa que o projeto do Google Cloud que você está usando não faz parte de um espaço de trabalho do Cloud Monitoring. Os espaços de trabalho são usados para organizar informações de monitoramento de projetos do Google Cloud, e a maioria dos métodos da API Monitoring requer que o projeto faça parte de um espaço de trabalho. Para mais informações, consulte Espaços de trabalho.

  • 401 UNAUTHENTICATED com "O usuário não está autorizado a acessar o projeto (ou a métrica)". Isso pode ser um problema de autorização, mas também pode significar que você digitou incorretamente o ID do projeto ou o nome do tipo de métrica. Verifique a ortografia e as letras maiúsculas.

    Se você não usa o API Explorer, tente usá-lo. Se a chamada de API funcionar no API Explorer, provavelmente você tem um problema de autorização no ambiente que está usando para a chamada da API. Verifique a página do gerenciador de APIs para verificar se a API Monitoring v3 está ativada para seu projeto.

  • 400 INVALID_ARGUMENT com "Filtro de campo tinha um valor inválido": verifique a ortografia e a formatação do filtro de monitoramento. Para mais informações, consulte Filtros de monitoramento.

  • 400 INVALID_ARGUMENT com "A solicitação não tinha o campo 'interval.endTime'": você verá esta mensagem se o horário de término estiver ausente ou se estiver presente, mas não estiver formatado corretamente. Se você estiver usando o API Explorer, não coloque o valor do campo de hora.

    Veja alguns exemplos de especificações de hora corretas:

    2016-05-11T01:23:45Z
    2016-05-11T01:23:45.678Z
    2016-05-11T01:23:45.678+05:00
    2016-05-11T01:23:45.678-04:30
    

Resultados ausentes

Se sua chamada de API retornar o código de status 200 e uma resposta vazia, há várias possibilidades:

  • Se sua chamada usa um filtro, o filtro pode não ter correspondido. A correspondência de filtro diferencia maiúsculas de minúsculas. Para resolver problemas de filtro, comece especificando apenas um componente de filtro, como metric.type, e veja se você recebe resultados. Adicione os outros componentes do filtro, um por um, para criar sua solicitação.

  • Se você estiver trabalhando com uma métrica personalizada, talvez não tenha especificado o projeto em que a métrica personalizada está definida.

Se você estiver buscando dados de série temporal usando timeSeries.list e alguns dos pontos de dados aparentarem estar ausentes, verifique as seguintes causas adicionais:

  • Se os dados tiverem mais de algumas semanas, talvez eles tenham expirado. Para mais informações, consulte Retenção de dados.

  • Se os dados tiverem sido gravados, talvez eles ainda não estejam no Monitoring. Para saber mais, consulte Latência dos dados de métrica.

  • Verifique se você especificou o intervalo de tempo corretamente:

    • Verifique se o horário de término está correto.
    • Verifique se o horário de início está correto e anterior ao horário de término. Se o horário de início estiver ausente ou malformado, o padrão será o valor de horário de término, e o intervalo de tempo corresponderá apenas a pontos em que os horários de início e término sejam exatamente o horário de término do intervalo. Isso é válido para métricas GAUGE, que medem um ponto no tempo, mas não para métricas CUMULATIVE ou DELTA, que medem intervalos de tempo. Para mais informações, consulte Intervalos de tempo.

Como repetir erros de API

Dois dos códigos de erro das APIs do Cloud indicam circunstâncias em que pode ser útil repetir a solicitação:

  • 503 UNAVAILABLE: novas tentativas serão úteis se o problema for uma condição de curta duração ou temporária.
  • 429 RESOURCE_EXHAUSTED: após um atraso, as novas tentativas só serão úteis para jobs de segundo plano de longa duração com cota de tempo, por exemplo, se você estiver limitado a n chamadas por t segundos. Mas se você tiver esgotado uma cota baseada em volume, novas tentativas não ajudarão. Você precisará aumentar sua cota.

Ao escrever um código que possa repetir solicitações, primeiro verifique se é seguro repeti-las.

É seguro repetir a solicitação?

Se a solicitação for idempotente, é seguro tentar novamente. Uma ação idempotente é aquela em que qualquer alteração no estado não depende do estado atual. Exemplo:

  • A leitura de x é idempotente, não haverá alteração no valor.
  • Definir x como 10 é idempotente. Isso pode alterar o estado, se o valor já não for 10, mas não importa qual é o valor atual e nem quantas vezes você tenta definir o valor.
  • Fazer um acréscimo em x não é idempotente. O novo valor depende do valor atual.

Repetição com espera exponencial

Ao implementar o código para repetir solicitações, você não quer emitir novas solicitações rápidas indefinidamente. Se um sistema estiver sobrecarregado, essa abordagem contribui para o problema.

Em vez disso, use uma abordagem de espera exponencial truncada. Quando as solicitações falham devido a sobrecargas temporárias em vez de indisponibilidade real, a solução é reduzir a carga. Uma espera exponencial truncada segue este padrão geral:

  • Estabeleça quanto tempo você pretende esperar ao tentar novamente ou quantas tentativas você pretende fazer. Quando esse limite for excedido, considere o serviço indisponível e lide com essa condição do aplicativo da maneira apropriada. Isso é o que cria a espera truncada, você parar de tentar novamente em algum momento.

  • Tente fazer a solicitação novamente com pausas cada vez mais longas para aumentar a espera da frequência das novas tentativas. Tente novamente até que a solicitação seja bem-sucedida ou o limite estabelecido seja atingido.

    O intervalo normalmente é aumentado por alguma função da potência da contagem de novas tentativas, tornando-a uma espera exponencial.

Há muitas maneiras de implementar uma espera exponencial. Veja um exemplo simples que adiciona um atraso de espera crescente a um atraso mínimo de 1.000 ms. O atraso inicial é de 2 ms e aumenta para 2retry_count ms a cada tentativa.

A tabela a seguir mostra os intervalos de repetição usando os valores iniciais:

  • Atraso mínimo = 1 s = 1.000 ms
  • Espera inicial = 2 ms
Contagem de repetições Atraso adicional (ms) Repetir após (ms)
0 20 = 1 1001
1 21 = 2 1002
2 22 = 4 1004
3 23 = 8 1008
4 24 = 16 1016
...
n 2n 1.000 + 2n

É possível truncar o ciclo de repetição ao parar após n tentativas ou quando o tempo gasto exceder um valor razoável para seu aplicativo.

Para mais informações, consulte o artigo da Wikipédia Exponential backoff (em inglês).