Pular para o conteúdo principal
Leia dados de métrica com a API pública (V2). Busque uma timeseries para gráficos, uma lista agregada para tabelas ou descubra quais métricas e tags um site possui. Todos os endpoints autenticam com seu token pessoal de API e têm escopo de um único site_id. Esta página explica como montar consultas de métrica. Para todos os campos de cada requisição e resposta, veja a referência dos endpoints de métricas.

Migrar das métricas GraphQL

Ler métricas pela API GraphQL está obsoleto. Se sua integração lê dados de métrica pelo GraphQL, use esta comparação para migrá-la para o endpoint de timeseries da API REST (V2).

Consultar uma timeseries

Este endpoint retorna uma ou mais séries de pontos de dados ao longo de um intervalo de tempo. Use-o para desenhar gráficos.
A requisição recebe um site_id, um intervalo de tempo from e to e um array select. Se você omitir resolution, a AppSignal escolhe uma adequada ao intervalo de tempo. Veja resoluções. Cada entrada de select solicita um campo de métrica. Informe um name de métrica, um objeto tags e um field (veja campos). Os valores de tag podem usar * como wildcard. Você também pode informar uma aggregation (veja agregações) e um valor de fill. Os valores de fill são ZERO (o padrão), PREVIOUS e NONE. Integrações existentes também podem usar o campo opcional draw_null_as_zero. true preenche os pontos ausentes com zero, como ZERO. false repete o valor anterior, como PREVIOUS. Se você enviar os dois campos, fill tem precedência. Use valores em maiúsculas para field e aggregation. O endpoint de timeseries não suporta group_by. A referência lista um campo limit, mas o endpoint de timeseries não o aplica. O número de séries é limitado pelos limites de processamento. Esta requisição busca a trace_duration média do namespace web. O draw_null_as_zero: false dela repete o último valor nos pontos ausentes.
A resposta tem um array series, com uma série por combinação de tag e campo que retornou dados. Diferente da API GraphQL de métricas, este endpoint não exige uma requisição separada de chaves de métrica. Use o array series para ver quais combinações de tag e campo retornaram dados. Se uma consulta puder atingir os limites de processamento, não use series.length como o número total de chaves de métrica correspondentes.

Consultar uma lista

Este endpoint retorna valores de métrica agregados agrupados em linhas. Use-o para construir tabelas.
A requisição recebe os mesmos site_id, from, to e resolution opcional de uma consulta de timeseries, mais um array group_by. Veja resoluções. Para limitar o número de linhas, adicione limit ou pagine a lista. Um seletor de lista é como um seletor de timeseries, com um id extra. O id nomeia o valor do seletor no objeto data de cada linha. Cada entrada de group_by é uma das seguintes, e ambas diferenciam maiúsculas e minúsculas:
  • A string "Name", para agrupar por nome da métrica.
  • Um objeto como {"Tag": "hostname"}, para agrupar pelo valor de uma tag.
Use valores em maiúsculas para field e aggregation. Se um seletor usar * para uma tag em tags, adicione a mesma tag a group_by como {"Tag": "tag_name"}, ou a requisição falha.
A resposta tem um array rows. Cada linha tem um objeto group com os valores de tag que a definem. O objeto data dela contém os valores agregados, indexados pelo id do seletor, por exemplo { "mean": 42.5 }.

Paginar uma lista

Adicione um objeto pagination ao corpo da requisição para ler a lista em páginas. Ele precisa destes três campos:
  • per_page: quantas linhas retornar por página.
  • order: ASC ou DESC. As linhas são ordenadas pelo id.
  • cursor: { "id": null } para a primeira página.
Se uma requisição tiver pagination e limit, pagination tem precedência. Para obter a próxima página, envie a mesma requisição com cursor.id definido como o id da última linha. Repita até que uma página retorne com menos linhas que per_page. Essa página é a última. Uma resposta paginada tem o mesmo formato de qualquer outra resposta de lista.
A paginação tem limites. Uma requisição fora deles retorna uma resposta 400 cujo campo error nomeia o problema:
  • per_page aceita valores de 1 a 1.000. Outros valores retornam pagination_invalid_per_page.
  • Uma consulta paginada lê até 100.000 chaves de métrica ou linhas em todas as suas páginas. Além desse limite, ela retorna pagination_key_limit_exceeded em vez de um resultado parcial. Restrinja os filtros de tag ou o intervalo de tempo e envie a requisição novamente.
  • Para métricas personalizadas, toda tag que usa um wildcard * também deve aparecer em group_by. O name da métrica não pode conter um wildcard. Caso contrário, a consulta retorna pagination_requires_deterministic_grouping.
  • As métricas de evento event_duration e event_metric, e a métrica de erro de incidente incident_error_count, ainda não podem ser paginadas. Elas retornam pagination_unsupported_for_selector. Consulte-as em uma requisição separada, sem pagination.

Listar nomes de métrica

Retorna todos os nomes de métrica disponíveis para um site.
Retorna um array de strings. Use um deles como o name nas entradas de select de uma consulta. Para ver como consultá-lo, obtenha o tipo e as tags dele. Para a resposta completa, veja a referência Listar nomes de métrica. Para restringir a lista, adicione um parâmetro de query filter, como ?filter=queue. Ele retorna apenas os nomes que contêm esse termo, sem diferenciar maiúsculas e minúsculas, com até 200 caracteres. Métricas personalizadas só aparecem se tiverem sido reportadas nas últimas 24 horas. A lista contém no máximo 1.000 delas, e filter busca além dessas 1.000.

Obter o tipo e as tags de uma métrica

Retorna o tipo de uma métrica e as combinações de tags com que ela pode ser consultada.
Retorna um metric_type (GAUGE, COUNTER ou MEASUREMENT) e available_tags, um array em que cada entrada é uma combinação válida de chaves de tag. O tipo define quais campos você pode selecionar. Uma métrica GAUGE tem o campo GAUGE, e uma métrica COUNTER tem o campo COUNTER. Uma métrica MEASUREMENT tem MEAN, COUNT, MIN, MAX e os percentis. Use uma combinação de tags como as chaves das tags de um seletor. Para a resposta completa, veja a referência Obter o tipo e as tags de uma métrica.

Timing do monitor de uptime

A métrica uptime_monitor_timing é um gauge que registra quanto tempo cada fase de uma verificação de uptime levou, em milissegundos. A tag phase seleciona a fase: dns, connect, tls, ttfb, download ou total. Veja o que cada fase mede em timing da requisição. Consulte a métrica com region, phase e o name ou o id do monitor. phase se comporta de forma diferente nos dois endpoints de consulta:
  • Em uma consulta de timeseries, phase aceita o wildcard * e retorna uma série por fase.
  • Em uma consulta de lista, cada seletor deve nomear uma fase. Adicione um seletor por fase desejada, e agrupe por region, name ou id, não por phase.
Uma fase que a verificação não mediu fica de fora da resposta. Isso se aplica a tls em uma URL HTTP simples e a download sem verificação de corpo. Esta requisição de lista retorna o tempo médio por fase e região para um monitor:

Métricas de log

A métrica log_metrics transforma linhas de log em números. Ela conta as linhas correspondentes, ou calcula a soma, a média, o mínimo ou o máximo de um campo numérico. A AppSignal a calcula no momento da consulta, então ela também cobre logs que você já enviou. Consulte-a pelo endpoint de timeseries ou de lista e configure-a com as tags do seletor: Para cada seletor:
  • Defina field como GAUGE. A tag aggregation define o valor; a propriedade aggregation do seletor é ignorada.
  • Inclua source_id e query. Sem eles, o seletor não retorna nada, e nenhum erro.
  • Nomeie os campos em notação de ponto, como user.age.
  • Agregue apenas campos do JSON do seu log. Campos nativos como severity retornam 400.
O intervalo de tempo é limitado à sua retenção de logs. Os resultados são agrupados assim:
  • Timeseries: uma série por combinação de group_by, com os valores dos campos como as tags da série.
  • Lista: uma linha por grupo, em todo o intervalo de tempo. Agrupe com o group_by da requisição, como [{"Tag": "severity"}]. Uma tag group_by no seletor retorna 400. Seletores que compartilham um grupo são mesclados em uma linha.
Esta requisição conta as linhas de signup e calcula a média da duration delas, por severidade:
O que saber sobre resultados de lista:
  • Uma linha omite um seletor cujo campo não tem valor numérico naquele grupo.
  • Linhas sem o campo agrupado são agrupadas sob uma string vazia.
  • O campo agregado não pode ser também um campo de group_by.
  • Sem paginação, limit limita cada seletor separadamente. Uma linha mesclada pode então não ter os valores de alguns seletores.
Agrupar por um campo com muitos valores, como um ID de usuário, deixa a consulta mais lenta.

Consultas de métrica de alta cardinalidade

Uma consulta de métrica tem alta cardinalidade quando corresponde a mais séries do que o endpoint pode processar. O AppSignal armazena cada combinação única de tag como uma chave de métrica separada. Por exemplo, cada combinação de valores de queue e worker cria uma chave de métrica separada. Os limites desta seção se aplicam a métricas personalizadas e a transaction_duration. Eles também se aplicam a incident_error_count quando uma consulta usa um wildcard para incident_digest ou revision. Eles não se aplicam a outras métricas na implementação V2 atual. Cada combinação de chave de métrica e campo conta como uma série. Por exemplo, solicitar MEAN e COUNT para uma chave de métrica conta como duas séries. Para métricas afetadas, o AppSignal limita quantas séries ele processa antes de buscar os dados delas:
  • /api/v2/metrics/timeseries processa até 100 séries.
  • /api/v2/metrics/list processa até 1.000 séries por página. Uma consulta paginada pode ler até 100.000 chaves de métrica em todas as suas páginas. Veja Paginar uma lista.
Esses limites protegem o banco de dados de métricas de consultas que demorariam demais para ser concluídas. Eles se aplicam à resposta inteira, não separadamente a cada entrada de select. O campo limit não pode aumentá-los. Os gráficos de dashboard carregam os dados de /api/v2/metrics/timeseries, então o limite de 100 séries também se aplica aos gráficos. Se uma consulta corresponder a mais séries do que o endpoint pode processar, o AppSignal retorna apenas parte dos dados. A resposta não indica que está incompleta, então os totais agregados podem ficar abaixo do real. Repetir a mesma consulta retorna o mesmo subconjunto, mas o resultado continua incompleto. Para ler mais séries de uma consulta de lista, pagine por ela. Uma consulta paginada que corresponde a mais de 100.000 chaves de métrica retorna pagination_key_limit_exceeded em vez de um resultado parcial. A página Limites mostra quais métricas personalizadas relatam mais combinações únicas de tag por minuto. Quando os valores de tag mudam com o tempo, uma consulta em um intervalo maior pode corresponder a mais séries do que a página mostra. Métricas personalizadas funcionam melhor com tags que têm um conjunto pequeno e fixo de valores, como region, plan ou queue. Se uma métrica existente tiver tags de alta cardinalidade, filtros de tag exatos podem reduzir o número de séries correspondentes, mas a resposta não pode confirmar que contém todas as séries. Veja Tags de métricas para orientações sobre como escolher valores de tag.

Referência

Campos

O field seleciona qual medição obter de uma métrica: Para ver quais campos uma métrica tem, obtenha o tipo e as tags dela. Para todos os tipos da API, veja a referência legível por máquina.

Agregações

A aggregation combina vários valores dentro de um bucket de tempo: SUM, AVERAGE, MIN, MAX, FIRST ou LAST. Se você omitir aggregation, o padrão depende do campo:

Resoluções

resolution aceita MINUTELY, HOURLY ou DAILY. MINUTELY se aplica apenas quando o intervalo é de 12 horas ou menos e começa nas últimas 48 horas. Fora dessa janela, o AppSignal usa HOURLY em vez disso e informa isso no campo resolution da resposta.