Consultando métricas - AppSignal Documentation

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.

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

O que você precisa	Métricas GraphQL	API REST (V2)
Endpoint	`POST https://appsignal.com/graphql?token=YOUR-TOKEN`	`POST https://appsignal.com/api/v2/metrics/timeseries`
Autenticação	Token pessoal de API em um parâmetro de query da URL	Token pessoal de API em um cabeçalho bearer ou em um parâmetro de query da URL. Veja autenticação.
Identificador do app	Passar o ID do app para `app(id: $appId)`	Passar o ID do app como `site_id` no corpo da requisição.
Filtros de tag	Um array de pares chave-valor, como `[{ "key": "namespace", "value": "web" }]`	Um objeto, como `{ "namespace": "web" }`
Campos	Um array `fields` em cada query de métrica	Um único `field` em maiúsculas em cada entrada de `select`, como `"MEAN"` ou `"P90"`. Use também valores em maiúsculas para `aggregation`.
Correspondência de dados	Consultar `app.metrics.keys` e `app.metrics.timeseries` separadamente.	Fazer uma única requisição de timeseries. O array `series` retornado identifica as combinações de tag e campo que retornaram dados. Os limites de processamento podem tornar essa lista incompleta.
Paginação	`metrics.list` e `metrics.keys` aceitam `limit` e `offset`.	Sem `offset`. O endpoint de lista aceita um objeto `pagination` com um cursor `id` de linha. Veja Paginar uma lista. O endpoint de timeseries não tem paginação, e seus resultados são limitados pelos limites de processamento.
Pontos de dados ausentes	A query de métrica não configura como preencher pontos ausentes.	Use o campo opcional `fill`. Ele aceita `"ZERO"`, `"PREVIOUS"` ou `"NONE"` e usa `"ZERO"` por padrão. O campo legado `draw_null_as_zero` também é suportado.

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.

POST /api/v2/metrics/timeseries

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`site_id`	string	Sim	Site a ser consultado.
`from`	string (ISO 8601)	Sim	Início do intervalo de tempo (inclusivo).
`to`	string (ISO 8601)	Sim	Fim do intervalo de tempo (inclusivo).
`select`	TimeseriesSelector[]	Sim	Quais métricas, campos e tags buscar.
`resolution`	Resolution	Não	Intervalo entre pontos de dados. Escolhido automaticamente quando omitido. Veja resoluções.
`limit`	number	Não	Número máximo de séries solicitadas para retorno. Este campo atualmente não é aplicado a consultas de timeseries.

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

{
  "site_id": "YOUR-SITE-ID",
  "from": "2026-06-22T00:00:00Z",
  "to": "2026-06-22T01:00:00Z",
  "resolution": "MINUTELY",
  "select": [
    {
      "name": "trace_duration",
      "tags": { "namespace": "web" },
      "field": "MEAN",
      "aggregation": "AVERAGE",
      "draw_null_as_zero": false
    }
  ]
}

Resposta

Retorna um Timeseries com a resolution, from, to consultados e um array series. Cada série tem um id, o name da métrica, suas tags, o field que ela representa, min e max no intervalo e um array data de pontos. Cada ponto tem um timestamp e um value numérico. 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.

POST /api/v2/metrics/list

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`site_id`	string	Sim	Site a ser consultado.
`from`	string (ISO 8601)	Sim	Início do intervalo de tempo (inclusivo).
`to`	string (ISO 8601)	Sim	Fim do intervalo de tempo (inclusivo).
`select`	ListSelector[]	Sim	Quais métricas, campos e tags buscar.
`group_by`	GroupBy[]	Sim	Como agrupar as linhas.
`resolution`	Resolution	Não	Intervalo usado para agregação. Veja resoluções.
`limit`	number	Não	Número máximo de linhas a retornar.
`pagination`	object	Não	Paginação baseada em cursor. Veja Paginar uma lista.

Um ListSelector é como um seletor de timeseries, com um id extra que nomeia o valor do seletor no objeto data de cada linha. As entradas de group_by são Name (agrupa por nome da métrica) ou Tag (agrupa pelo valor de uma tag). Use valores em maiúsculas para field e aggregation. Os valores de group_by, sensíveis a maiúsculas e minúsculas, são Name e Tag. 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.

{
  "site_id": "YOUR-SITE-ID",
  "from": "2026-06-22T00:00:00Z",
  "to": "2026-06-22T01:00:00Z",
  "resolution": "HOURLY",
  "select": [
    {
      "id": "mean",
      "name": "trace_duration",
      "tags": { "namespace": "*" },
      "field": "MEAN",
      "aggregation": "AVERAGE"
    }
  ],
  "group_by": [{ "Tag": "namespace" }],
  "limit": 50
}

Resposta

Retorna uma List com a resolution, from, to consultados e um array rows. Cada linha tem um id, um objeto group com os valores de tag que a definem e um objeto data com 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:

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.

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.

{
  "site_id": "YOUR-SITE-ID",
  "from": "2026-06-22T00:00:00Z",
  "to": "2026-06-22T01:00:00Z",
  "resolution": "HOURLY",
  "select": [
    {
      "id": "mean",
      "name": "trace_duration",
      "tags": { "namespace": "*" },
      "field": "MEAN",
      "aggregation": "AVERAGE"
    }
  ],
  "group_by": [{ "Tag": "namespace" }],
  "pagination": {
    "per_page": 100,
    "order": "ASC",
    "cursor": { "id": null }
  }
}

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.

GET /api/v2/metrics/names/{site_id}

Retorna um array de strings.

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.

GET /api/v2/metrics/type_and_tags/{site_id}/{metric_name}

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.

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:

{
  "site_id": "YOUR-SITE-ID",
  "from": "2026-10-08T08:00:00Z",
  "to": "2026-10-08T09:00:00Z",
  "resolution": "HOURLY",
  "select": [
    {
      "id": "dns",
      "name": "uptime_monitor_timing",
      "tags": { "id": "YOUR-MONITOR-ID", "region": "*", "phase": "dns" },
      "field": "GAUGE",
      "aggregation": "AVERAGE"
    },
    {
      "id": "ttfb",
      "name": "uptime_monitor_timing",
      "tags": { "id": "YOUR-MONITOR-ID", "region": "*", "phase": "ttfb" },
      "field": "GAUGE",
      "aggregation": "AVERAGE"
    }
  ],
  "group_by": [{ "Tag": "region" }]
}

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:

Valor	Descrição
`GAUGE`	O valor da métrica em um único instante, como uso atual de CPU ou memória.
`COUNTER`	De métricas `COUNTER`, o valor cumulativo, que só aumenta com o tempo, como o número de requisições atendidas.
`MEAN`	A média dos valores registrados no bucket de tempo, como tempo médio de resposta.
`COUNT`	De métricas `MEASUREMENT`, quantos valores foram registrados durante o bucket de tempo.
`MIN`	O menor valor registrado no bucket de tempo.
`MAX`	O maior valor registrado no bucket de tempo.
`P99`, `P95`, `P90`, `P80`, `P75`, `P70`, `P60`, `P50`, `P40`, `P30`, `P20`, `P10`	Valores de percentil.

Para mais referências de tipo, leia a documentação da API V2 da AppSignal.

Agregações

A aggregation combina vários valores dentro de um bucket de tempo: SUM, AVERAGE, MIN, MAX, FIRST ou LAST.

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.

​Migrar das métricas GraphQL

​Consultar uma timeseries

​Corpo da requisição

​Resposta

​Consultar uma lista

​Corpo da requisição

​Resposta

​Paginar uma lista

​Listar nomes de métrica

​Obter o tipo e as tags de uma métrica

​Timing do monitor de uptime

​Consultas de métrica de alta cardinalidade

​Referência

​Campos

​Agregações

​Resoluções

Migrar das métricas GraphQL

Consultar uma timeseries

Corpo da requisição

Resposta

Consultar uma lista

Corpo da requisição

Resposta

Paginar uma lista

Listar nomes de métrica

Obter o tipo e as tags de uma métrica

Timing do monitor de uptime

Consultas de métrica de alta cardinalidade

Referência

Campos

Agregações

Resoluções