Resolver problemas na API Monitoring

Neste guia, explicamos 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. Ele permite invocar o método preenchendo campos. Não é necessário escrever código.

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 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 capitalização, 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 normalmente 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 APIs 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 no 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 estava sem campo de intervalo.endTime"": essa mensagem é exibida quando não há um horário de término ou quando ele está presente, mas não está formatado corretamente. Se você estiver usando as APIs Explorer, não coloque o valor do campo de hora entre aspas.

    Veja 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 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, ele pode não ter correspondência com nada. A correspondência de filtro diferencia maiúsculas de minúsculas. Para resolver problemas no filtro, comece especificando apenas um componente, como metric.type, e verifique se aparece 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 está especificado.

Há vários motivos para os pontos de dados estarem ausentes ao usar o método timeSeries.list:

  • Os dados podem estar envelhecidos. 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 se é anterior ao horário de término. Quando o horário de início está ausente ou é incorreto, a API define o horário de início como o de término. Para métricas GAUGE, esse intervalo de tempo corresponde apenas aos pontos cujos horários de início e término são exatamente os horários de término do intervalo. Para as métricas CUMULATIVE ou DELTA, que medem intervalos de tempo, nenhum ponto é correspondido. 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: novas tentativas são úteis, após um atraso, para jobs em segundo plano de longa duração com cota baseada em tempo, como n chamadas por t segundos. As novas tentativas não são úteis quando o problema é uma condição temporária ou de curta duração ou quando você esgotou uma cota baseada em volume. Para condições temporárias, considere tolerar a falha. No caso de problemas relacionados a cotas, reduza 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 a seguir um exemplo que adiciona um atraso crescente de espera 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).