Resolver problemas na API Monitoring

Este guia explica alguns dos problemas que podem surgir ao usar a API Monitoring.

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 o APIs Explorer para depuração

As APIs 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 das APIs Explorer (Try this API) na página de referência desse método para depurar o problema. Para mais informações, consulte o APIs Explorer.

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 com "O URL solicitado não foi encontrado neste servidor": parte do URL está incorreta. Compare o URL com o URL do método mostrado na página de referência do método. Esse erro pode significar que há um erro de ortografia, como "projeto" em vez de "projetos", ou um erro de letras maiúsculas, como "TimeSeries" em vez de "timeSeries".

• 401 UNAUTHENTICATED com "O usuário não está autorizado a acessar o projeto (ou a métrica)": esse código de erro geralmente indica um problema de autorização, mas pode significar que há um erro no ID do projeto ou no nome do tipo de métrica. Verifique a ortografia e as letras maiúsculas.

  Se você não usa o APIs Explorer, tente usá-lo. Quando a chamada de API funciona no API Explorer, provavelmente há um problema de autorização no ambiente em que você está fazendo a chamada de API. Acesse a página do Gerenciador de APIs para verificar se a API Monitoring está ativada para 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 monitoramento. Para mais informações, consulte Filtros de monitoramento.

• 400 INVALID_ARGUMENT com "A solicitação não tinha o campo interval.endTime": essa mensagem aparece quando o horário de término está ausente ou quando está presente, mas não está formatado corretamente. Se você estiver usando o APIs Explorer, não cite o valor do campo de tempo.

  Confira alguns exemplos de especificações de hora 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 ausentes

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

• Quando a chamada usa um filtro, o filtro pode não ter correspondido a nada. 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 verifique se você recebe resultados. Adicione os outros componentes do filtro, um por um, para criar sua solicitação.

• Ao trabalhar com uma métrica personalizada, verifique se o projeto que define a métrica foi especificado.

Há vários motivos para os pontos de dados não aparecerem quando você usa o método timeSeries.list:

• Os dados podem estar desatualizados. Para mais informações, consulte Retenção de dados.

• Talvez os dados ainda não tenham sido propagados para o Monitoring. Para saber mais, consulte Latência dos dados de métrica.

• O intervalo é inválido:

  • Verifique se o horário de término está correto.
  • Verifique se o horário de início está correto e é anterior ao de término. Quando o horário de início está ausente ou malformado, a API define o horário de início como o horário de término. Para métricas GAUGE, esse intervalo de tempo só corresponde a pontos em que os horários de início e término são exatamente o horário de término do intervalo. Para métricas CUMULATIVE ou DELTA, que medem intervalos de tempo, nenhum ponto é correspondente. 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 são úteis quando o problema é 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, 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 você esgotou uma cota baseada em volume. Para condições temporárias, considere tolerar a falha. Para problemas relacionados à cota, reduz o uso da cota ou solicite um aumento.

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. Confira um exemplo 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 2^retry_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	2^0 = 1	1001
1	2^1 = 2	1002
2	2^2 = 4	1004
3	2^3 = 8	1008
4	2^4 = 16	1016
…	…	…
n	2^n	1.000 + 2^n

É 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).