Esta página foi traduzida pela API Cloud Translation.

Como monitorar o uso de APIs

Nesta página, descrevemos como usar as métricas da API para acompanhar e entender seu uso. das APIs do Google e das APIs do Google Cloud.

As APIs do Google produzem métricas de uso detalhadas que podem ajudá-lo a:

acompanhar e entender seu uso de APIs do Google;
monitorar o desempenho dos seus aplicativos e APIs do Google;
descobrir problemas entre seus aplicativos e as APIs do Google.

Isso acelera drasticamente os tempos de resolução quando você soluciona problemas ou precisa de suporte técnico do Google.

As métricas que as APIs do Google produzem são os sinais padrão que os engenheiros de confiabilidade do site do Google usam para avaliar a integridade de um serviço. Essas métricas abrangem contagens de solicitações, taxas de erro, latências totais, latências de back-end, tamanhos de solicitações e tamanhos de resposta. Para definições de métricas de API, consulte a documentação do Cloud Monitoring.

É possível visualizar as métricas da API em dois locais: Painel de APIs e Cloud Monitoring. As métricas que você vê são específicas para seu projeto e não refletem o status geral do serviço.

Como usar o Painel de APIs

A maneira mais simples de visualizar as métricas da API é usar o Painel de APIs do console do Cloud. Você pode ter uma visão geral de todas as métricas de uso da API ou detalhar o uso de uma API específica.

Para uma visão geral do uso da API:

Acesse a seção APIs e serviços do console do Cloud. O painel principal da API é exibido por padrão. Nesta página, você pode ver todas as APIs que se encontra ativadas para seu projeto, além de gráficos de visão geral para as seguintes métricas:
- Tráfego: o número de solicitações por segundo para APIs ativadas feitas pelo seu projeto ou relacionadas com ele
- Erros: a porcentagem de solicitações para APIs ativadas que resultaram em erros.
- Latência mediana: a latência mediana para solicitações a APIs ativadas (caso disponíveis).

Para ver os detalhes de uso de uma API específica:

Selecione a API que você quer visualizar na lista principal de APIs do Painel de APIs. A página Visão geral da API mostra um gráfico de tráfego mais esmiuçado com um detalhamento por código de resposta.
Para informações de uso ainda mais detalhadas, selecione Ver métricas. Por padrão, os seguintes gráficos pré-criados são exibidos, embora outros estejam disponíveis:
- Tráfego por código de resposta
- Erros por método da API
- Latência geral no percentis 50º, 95º e 99º
- Latência por método da API (média)
Se quiser adicionar mais gráficos, selecione outros gráficos pré-criados no menu suspenso Selecionar gráficos.

Como usar o Cloud Monitoring

Se você usa o Cloud Monitoring, pode se aprofundar nos dados de métricas disponíveis usando o Metrics Explorer para fornecer mais informações sobre o uso da API. O Cloud Monitoring é compatível com várias métricas, que podem ser combinadas com filtros e agregações para conseguir novas visualizações sobre o desempenho do seu aplicativo. Por exemplo, você pode combinar uma métrica de contagem de solicitações com um filtro na classe Código de resposta HTTP para criar um painel que mostre as taxas de erro ao longo do tempo ou observar a latência do percentil 95º de solicitações à API Cloud Pub/Sub.

Métricas disponíveis

A tabela a seguir lista as métricas de serviceruntime disponíveis. As métricas de uso da API são aquelas que incluem consumed_api como um recurso monitorado.

As strings "tipo de métrica" nesta tabela precisam ser prefixadas com serviceruntime.googleapis.com/. Esse prefixo foi omitido das entradas na tabela. Ao consultar um rótulo, use o prefixo metric.labels.. por exemplo, metric.labels.LABEL="VALUE".

Tipo de métrica ^{Etapa do lançamento} (níveis da hierarquia de recursos) Nome de exibição
Classe, Tipo, Unidade Recursos monitorados	Descrição Rótulos
`api/request_count` ^GA *(project)* Contagem de solicitações
`DELTA`, `INT64`, `1` api consumed_api produced_api	A contagem de solicitações concluídas. Amostras coletadas a cada 60 segundos. Após a amostragem, os dados não são visíveis por até 1.800 segundos. `protocol`: O protocolo da solicitação, por exemplo, "http", "grpc". `response_code`: O código de resposta HTTP para solicitações HTTP ou o código HTTP equivalente para solicitações gRPC. Veja o mapeamento de código em https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto. `response_code_class`: A classe do código de resposta para solicitações HTTP ou a classe equivalente do HTTP para solicitações gRPC, por exemplo, "2xx", "4xx". `grpc_status_code`: O código numérico de resposta gRPC para solicitações gRPC ou o código equivalente do gRPC para solicitações HTTP. Veja o mapeamento de código em https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto.
`api/request_latencies` ^GA *(project)* Latências de solicitação
`DELTA`, `DISTRIBUTION`, `s` api consumed_api produced_api	Distribuição de latências em segundos para solicitações que não são de streaming. Amostras coletadas a cada 60 segundos. Após a amostragem, os dados não são visíveis por até 1.800 segundos.
`api/request_latencies_backend` ^GA *(projeto)* Solicitar latências de back-end
`DELTA`, `DISTRIBUTION`, `s` api produced_api	Distribuição de latências de back-end em segundos para solicitações que não são de streaming. Amostras coletadas a cada 60 segundos. Após a amostragem, os dados não são visíveis por até 1.800 segundos.
`api/request_latencies_overhead` ^GA *(projeto)* Solicitar latências de sobrecarga
`DELTA`, `DISTRIBUTION`, `s` api produced_api	Distribuição de latências de solicitação em segundos para solicitações sem streaming, exceto o back-end. Amostras coletadas a cada 60 segundos. Após a amostragem, os dados não são visíveis por até 1.800 segundos.
`api/request_sizes` ^GA *(projeto)* Tamanhos das solicitações
`DELTA`, `DISTRIBUTION`, `By` api consumed_api produced_api	Distribuição de tamanhos de solicitação em bytes registrados na conclusão da solicitação. Amostras coletadas a cada 60 segundos. Após a amostragem, os dados não são visíveis por até 1.800 segundos.
`api/response_sizes` ^GA *(projeto)* Tamanhos das respostas
`DELTA`, `DISTRIBUTION`, `By` api consumed_api produced_api	Distribuição de tamanhos de resposta em bytes registrados na conclusão da solicitação. Amostras coletadas a cada 60 segundos. Após a amostragem, os dados não são visíveis por até 1.800 segundos.
`quota/allocation/usage` ^GA *(projeto, pasta, organização)* Uso da cota de alocação
`GAUGE`, `INT64`, `1` consumer_quota producer_quota	A cota de alocação total consumida. Os valores informados mais de 1/min são descartados. Se não houver mudanças no uso da cota, o último valor será repetido pelo menos a cada 24 horas. Amostras coletadas a cada 60 segundos. `quota_metric`: O nome da métrica ou do grupo de cota.
`quota/concurrent/exceeded` ^ALFA *(project, folder, organization)* Excedeu a cota simultânea
`DELTA`, `INT64`, `1` consumer_quota	O número de vezes que houve uma tentativa de exceder a cota simultânea. Amostras coletadas a cada 86.400 segundos. Após a amostragem, os dados não são visíveis por até 180 segundos. `limit_name`: O nome do limite de cota, como "Solicitações por dia" ou "Endereços IP em uso". `quota_metric`: O nome da métrica ou do grupo de cota. `time_window`: O tamanho da janela para limites de operação simultânea.
`quota/concurrent/limit` ^ALPHA *(projeto, pasta, organização)* Limite de cota simultânea
`GAUGE`, `INT64`, `1` consumer_quota producer_quota	O limite simultâneo para a cota. Amostras coletadas a cada 86.400 segundos. Após a amostragem, os dados não são visíveis por até 180 segundos. `limit_name`: O nome do limite de cota, como "Solicitações por dia" ou "Endereços IP em uso". `quota_metric`: O nome da métrica ou do grupo de cota. `time_window`: O tamanho da janela para limites de operação simultânea.
`quota/concurrent/usage` ^ALPHA *(projeto, pasta, organização)* Uso de cota simultâneo
`GAUGE`, `INT64`, `1` consumer_quota producer_quota	O uso simultâneo da cota. Amostras coletadas a cada 60 segundos. Após a amostragem, os dados não são visíveis por até 180 segundos. `limit_name`: O nome do limite de cota, como "Solicitações por dia" ou "Endereços IP em uso". `quota_metric`: O nome da métrica ou do grupo de cota. `time_window`: O tamanho da janela para limites de operação simultânea.
`quota/exceeded` ^GA *(project, folder, organization)* Erro de cota excedida
`GAUGE`, `BOOL`, `1` consumer_quota	O erro ocorreu quando o limite de cota foi excedido. Amostras coletadas a cada 60 segundos. `limit_name`: O nome do limite de cota, como "Solicitações por dia" ou "Endereços IP em uso". `quota_metric`: O nome da métrica ou do grupo de cotas.
`quota/limit` ^GA *(projeto, pasta, organização)* Limite de cota
`GAUGE`, `INT64`, `1` consumer_quota producer_quota	O limite da cota. Amostras coletadas a cada 86.400 segundos. `limit_name`: O nome do limite de cota, como "Solicitações por dia" ou "Endereços IP em uso". `quota_metric`: O nome da métrica ou do grupo de cota.
`quota/rate/net_usage` ^GA *(projeto, pasta, organização)* Uso da cota de taxa
`DELTA`, `INT64`, `1` consumer_quota producer_quota	A cota total de taxa consumida. Amostras coletadas a cada 60 segundos. Após a amostragem, os dados não são visíveis por até 240 segundos. `method`: O nome do método da API, como "disks.list". `quota_metric`: O nome da métrica ou do grupo de cota.
`reserved/metric1` ^EARLY_ACCESS *(project)* Descontinuado
`DELTA`, `INT64`, `1` deprecated_resource	Obsoleto. Amostras coletadas a cada 60 segundos. Após a amostragem, os dados não são visíveis por até 180 segundos. `quota_name`: descontinuado. `credential_id`: descontinuado. `quota_location`: descontinuado.

Tabela gerada em 10-10-2024 16:45:27 UTC.

Para acessar as métricas da API no Metrics Explorer, selecione API utilizada como recurso tipo e selecione uma das métricas serviceruntime. Em seguida, use as opções de filtro e agregação para refinar seus dados. Depois de encontrar as informações de uso da API que você queria, use o Cloud Monitoring para criar alertas e painéis personalizados que ajudarão você a continuar monitorando e mantendo um aplicativo robusto. Descubra como fazer isso nas seguintes páginas:

Para mais informações, consulte Metrics Explorer.

Solução de problemas com métricas de API

As métricas de API podem ser especialmente úteis se você precisar entrar em contato com o Google quando algo der errado e até mesmo mostrar que você não precisa entrar em contato com o suporte. Exemplo:

Se todas as suas chamadas para um serviço estiverem falhando para um único código de credencial, mas nenhum outro, provavelmente há algo errado com essa conta que você pode corrigir sem abrir um tíquete.
Você está solucionando um problema com seu aplicativo e percebe uma correlação entre o desempenho prejudicado do aplicativo e um aumento contínuo na latência do percentil 50º de um serviço crítico do GCP. Não deixe de entrar em contato conosco e nos indicar esses dados para que comecemos a trabalhar na solução do problema o quanto antes.
As latências de um relatório de serviços do GCP parecem boas e sem sofrer alterações, mas as métricas no aplicativo informam que a latência nas chamadas ao serviço está alta demais. Isso indica que há algum problema na rede. Entre em contato com o provedor de rede (em alguns casos, o Google) para iniciar o processo de depuração.

Práticas recomendadas

Embora as métricas da API sejam uma ferramenta muito proveitosa, pense em algumas questões para garantir que elas forneçam informações úteis, principalmente ao configurar alertas com base em valores de métricas. As práticas recomendadas a seguir ajudarão você a aproveitar ao máximo os dados das métricas da API.

A latência está causando um problema?

Embora alguns serviços sejam bastante sensíveis à latência, para outros, a escala e a confiabilidade são mais importantes. Algumas APIs, como a do Cloud Storage ou a do BigQuery, podem ter alguns segundos de alta latência sem que os clientes percebam. Com os dados das métricas da API, você sabe o que seus usuários demandam de um determinado serviço.

Procurar alterações da norma

Antes de decidir criar um alerta para um determinado valor de métrica, observe o que realmente deve ser considerado um comportamento incomum. Observar suas métricas de API pode mostrar que os resultados de latência para a maioria dos serviços estão dentro de uma distribuição normal: um valor alto no meio e valores baixos nas pontas. Com as métricas, você entende a distribuição normal e desenvolve seu aplicativo para funcionar bem na curva de distribuição. As métricas também podem ajudar a correlacionar as alterações de distribuição com os horários em que o aplicativo não está funcionando conforme o esperado. Isso ajuda a encontrar a causa principal de um problema. Nossa expectativa é que o percentil 99º tenha uma aparência muito diferente da média. Não contamos com mudanças drásticas nesses percentis ao longo do tempo.

Além disso, você pode ver que alguns tipos de solicitações demoram mais do que outros. Se o tamanho médio de uma foto enviada para o Google Fotos for 4 MB, mas você normalmente carrega 20 MB de arquivos RAW, é provável que o tempo médio para enviar 20 fotos seja substancialmente pior do que o da maioria dos usuários, embora ainda seja seu comportamento normal.

Tudo isso significa que não é particularmente útil criar um alerta na primeira vez em que é detectada uma chamada RPC de mais de um segundo ou uma chamada HTTP 5xx. Em vez disso, ao investigar um serviço do Google como possível causa de um problema que seu aplicativo está enfrentando, compare os códigos de retorno e as taxas de latência ao longo do tempo e procure alterações contínuas da norma relacionadas aos problemas observados em seu aplicativo.

Taxa de tráfego

As métricas de API são mais úteis quando você tem um volume alto de tráfego indo para a API. Se você chamar um serviço apenas de forma intermitente, suas métricas de API não serão válidas do ponto de vista estatístico e não fornecerão informações significativas de triagem.

Por exemplo, se você quiser acompanhar a latência do percentil 99,5º para um serviço e fizer somente 100 chamadas por hora, observar a medição durante duas horas forneceria apenas um ponto de dados para representar o percentil 99,5º, que não dirá muito sobre o comportamento normal da API ou do aplicativo. Certifique-se de que a taxa de tráfego, o percentil que você está acompanhando e o intervalo que está considerando geram muitos pontos de dados de interesse. Do contrário, os dados de monitoramento não serão úteis.

APIs compatíveis

Todas as APIs do Google e do Google Cloud, bem como as criadas sobre o Cloud Endpoints e o gateway de API, aceitam as métricas de API. Se você é um consumidor de APIs, pode ver as métricas da API consumidas no Painel de APIs. Se for um produtor de APIs, poderá visualizar as métricas da API produzida no Painel do Endpoints.