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.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.
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.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.
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.
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 objetopagination 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:ASCouDESC. As linhas são ordenadas peloid.cursor:{ "id": null }para a primeira página.
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.
400
cujo campo error nomeia o problema:
per_pageaceita valores de 1 a 1.000. Outros valores retornampagination_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_exceededem 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 emgroup_by. Onameda métrica não pode conter um wildcard. Caso contrário, a consulta retornapagination_requires_deterministic_grouping. - As métricas de evento
event_durationeevent_metric, e a métrica de erro de incidenteincident_error_count, ainda não podem ser paginadas. Elas retornampagination_unsupported_for_selector. Consulte-as em uma requisição separada, sempagination.
Listar nomes de métrica
Retorna todos os nomes de métrica disponíveis para um site.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.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étricauptime_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,
phaseaceita 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,nameouid, não porphase.
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étricalog_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
fieldcomoGAUGE. A tagaggregationdefine o valor; a propriedadeaggregationdo seletor é ignorada. - Inclua
source_idequery. 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
severityretornam400.
- Timeseries: uma série por combinação de
group_by, com os valores dos campos como astagsda série. - Lista: uma linha por grupo, em todo o intervalo de tempo. Agrupe com o
group_byda requisição, como[{"Tag": "severity"}]. Uma taggroup_byno seletor retorna400. Seletores que compartilham um grupo são mesclados em uma linha.
signup e calcula a média da duration
delas, por severidade:
- 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,
limitlimita cada seletor separadamente. Uma linha mesclada pode então não ter os valores de alguns seletores.
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 dequeue 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/timeseriesprocessa até 100 séries./api/v2/metrics/listprocessa 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.
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
Ofield 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
Aaggregation 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.