Resolva problemas da API Monitoring

Este guia explica alguns dos problemas que podem surgir quando usa a API Monitoring.

A API Monitoring é um dos conjuntos de APIs Google Cloud. Estas APIs partilham um conjunto comum de códigos de erro. Para ver uma lista dos códigos de erro definidos pelas APIs Cloud e sugestões gerais sobre como processar os erros, consulte o artigo Processamento de erros.

Use o Explorador de APIs para depuração

O Explorador de APIs é um widget incorporado nas páginas de referência dos métodos da API. Permite-lhe invocar o método preenchendo campos; não é necessário escrever código.

Se estiver com problemas com uma invocação de método, use o widget do Explorador de APIs (Experimentar esta API) na página de referência desse método para depurar o seu problema. Para mais informações, consulte o Explorador de APIs.

Erros gerais da API

Seguem-se alguns dos erros e mensagens da API Monitoring que pode ver nas suas chamadas API:

  • 404 NOT_FOUND com "Não foi possível encontrar o URL pedido neste servidor": Alguma parte do URL está incorreta. Compare o URL com o URL do método apresentado na página de referência do método. Este erro pode significar que existe um erro ortográfico, como "project" em vez de "projects", ou um erro de utilização de letras maiúsculas, como "TimeSeries" em vez de "timeSeries".

  • 401 UNAUTHENTICATED com "O utilizador não está autorizado a aceder ao projeto (ou à métrica)": este código de erro indica normalmente um problema de autorização, mas pode significar que existe um erro no ID do projeto ou no nome do tipo de métrica. Verifique a ortografia e a utilização de maiúsculas/minúsculas.

    Se não estiver a usar o Explorador de APIs, experimente usá-lo. Quando a chamada de API funciona no Explorador de APIs, é provável que exista um problema de autorização no ambiente em que está a fazer a chamada de API. Aceda à página do gestor de APIs para verificar se a API Monitoring está ativada para o seu projeto.

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

  • 400 INVALID_ARGUMENT com "Request was missing field interval.endTime": Esta mensagem é apresentada quando a hora de fim está em falta ou quando está presente, mas não está formatada corretamente. Se estiver a usar o Explorador de APIs, não coloque o valor do campo de tempo entre aspas.

    Seguem-se alguns exemplos de especificações de tempo válidas:

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

Resultados em falta

Quando uma chamada API devolve o código de estado 200 e uma resposta vazia, considere o seguinte:

  • Quando a chamada usa um filtro, o filtro pode não ter encontrado nenhum resultado. A correspondência do filtro é sensível a maiúsculas e minúsculas. Para resolver problemas de filtros, comece por especificar apenas um componente de filtro, como metric.type, e verifique se obtém resultados. Adicione os outros componentes de filtro um a um para criar o seu pedido.
  • Quando trabalhar com uma métrica personalizada, verifique se o projeto que define a métrica está especificado.

Existem vários motivos pelos quais os pontos de dados podem estar em falta quando usa o método timeSeries.list:

  • Os dados podem ter ficado obsoletos. Para mais informações, consulte o artigo Retenção de dados.

  • Os dados podem ainda não ter sido propagados para a Monitorização. Para mais informações, consulte o artigo Latência dos dados de métricas.

  • O intervalo é inválido:

    • Verifique se a hora de fim está correta.
    • Verifique se a hora de início está correta e se é anterior à hora de fim. Quando a hora de início está em falta ou está incorreta, a API define a hora de início como a hora de fim. Para as métricas GAUGE, este intervalo de tempo só corresponde a pontos cujas horas de início e de fim sejam exatamente a hora de fim do intervalo. Para as métricas CUMULATIVE ou DELTA, que medem em intervalos de tempo, não são encontrados pontos correspondentes. Para mais informações, consulte o artigo Intervalos de tempo.

Voltar a tentar erros da API

Dois dos códigos de erro das APIs Cloud indicam circunstâncias em que pode ser útil tentar novamente o pedido:

  • 503 UNAVAILABLE: as novas tentativas são úteis quando o problema é uma condição de curta duração ou transitória.
  • 429 RESOURCE_EXHAUSTED: as novas tentativas são úteis, após um atraso, para tarefas em segundo plano de execução prolongada com quota baseada no tempo, como n chamadas por t segundos. As novas tentativas não são úteis quando o problema é uma condição de curta duração ou transitória, ou quando esgotou uma quota baseada no volume. Para condições transitórias, considere tolerar a falha. Para problemas relacionados com a quota, pondere reduzir a utilização da quota ou pedir um aumento da quota.

Ao escrever código que possa repetir pedidos, certifique-se primeiro de que o pedido é seguro para repetir.

O pedido é seguro para tentar novamente?

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

  • A leitura de x é idempotente; não existe nenhuma alteração ao valor.
  • Definir x como 10 é idempotente. Isto pode alterar o estado, se o valor ainda não for 10, mas não importa qual seja o valor atual. Além disso, não importa quantas vezes tenta definir o valor.
  • O incremento de x não é idempotente. O novo valor depende do valor atual.

Tente novamente com retirada exponencial

Quando implementar código para repetir pedidos, não deve emitir rapidamente novos pedidos indefinidamente. Se um sistema estiver sobrecarregado, esta abordagem contribui para o problema.

Em alternativa, use uma abordagem de retirada exponencial truncada. Quando os pedidos falham devido a sobrecargas temporárias em vez de indisponibilidade real, a solução é reduzir a carga. Uma retirada exponencial truncada segue este padrão geral:

  • Estabeleça quanto tempo está disposto a esperar enquanto tenta novamente ou quantas tentativas está disposto a fazer. Quando este limite é excedido, considere o serviço indisponível e processe essa condição adequadamente para a sua aplicação. É isto que torna o recuo truncado. Deixa de tentar novamente a certa altura.

  • Tente novamente o pedido com pausas cada vez mais longas para reduzir a frequência de novas tentativas. Volte a tentar até que o pedido seja bem-sucedido ou que o limite estabelecido seja atingido.

    Normalmente, o intervalo é aumentado por alguma função da potência da contagem de novas tentativas, o que o torna uma retirada exponencial.

Existem muitas formas de implementar um recuo exponencial. Segue-se um exemplo que adiciona um atraso de recuo crescente a um atraso mínimo de 1000 ms. O atraso de recuo inicial é de 2 ms e aumenta para 2retry_count ms com cada tentativa.

A tabela seguinte mostra os intervalos de repetição com os valores iniciais:

  • Atraso mínimo = 1 s = 1000 ms
  • Recuo inicial = 2 ms
Número de tentativas Atraso adicional (ms) Voltar a tentar 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 1000 + 2n

Pode truncar o ciclo de repetição parando após n tentativas ou quando o tempo gasto exceder um valor razoável para a sua aplicação.

Para mais informações, consulte o artigo da Wikipédia Retirada exponencial.