site_ids, para que possam buscar em vários
sites em uma única requisição. Os outros recebem um único site_id.
Localizar um trace
Encontre as ações de performance e os incidentes de erro em que um trace aparece, entre sites.site_ids (um array de strings) e trace_id (uma
string). A resposta tem entradas performance, com o namespace e o
action_name, e entradas errors, com o incident_number e o
exception_name. Cada entrada errors também tem incident_digests. Passe-os
como digests para os endpoints de traces de erro.
Obter os spans de um trace
Retorna cada span de um trace.site_ids (um array de strings) e trace_id (uma
string). Para retornar também spans de outros traces que se vinculam a este,
defina include_linked_spans como true.
POST /api/v2/tracing/trace/performancerecebe umaction_namee umnamespace.POST /api/v2/tracing/trace/errorrecebe osdigestsde um incidente de erro.
trace_id dele.
Listar traces
Liste traces de performance ou erro.traces/performanceprecisa de umaction_namee umnamespace. Adicioneduration_mspara listar apenas traces com pelo menos essa duração. Adicionefrometopara definir um intervalo de tempo.traces/errorsprecisa dosdigestsdos incidentes de erro. Ele não tem intervalo de tempo.
query opcional para filtrar por revisão ou tag, e ambos
precisam de um objeto pagination.
pagination precisa destes três campos:
per_page: quantos traces retornar por página, até 100.order:ASCouDESC.cursor:{ "time": null }para ordenar pelo horário do trace, ou{ "duration": null }para ordenar pela duração do trace.nullcomeça da primeira página.
trace_id, o time em que o trace começou e a
duration total dele em milissegundos.
Buscar traces
Busque dados de erros e de performance em vários sites, por ação, exceção, tag ou mensagem.site_ids: pelo menos um site, todos na mesma conta. A
query opcional corresponde assim:
- Palavras soltas correspondem exatamente a um nome de ação, nome de exceção ou valor de tag, como uma única frase.
action:,error:etag:correspondem exatamente a um campo.message:corresponde a uma frase de palavras inteiras, sem diferenciar maiúsculas e minúsculas.
namespace, um intervalo from e to, ou um kind.
kind é all (o padrão), exception ou performance. from tem como padrão
o início da retenção da sua conta, e to tem como padrão o momento atual.
A resposta contém até limit resultados, os mais recentes primeiro. limit
tem padrão 50 e máximo de 2.000. Cada resultado é um digest de incidente de um
span correspondente, então um trace_id pode aparecer mais de uma vez.
Listar ações de performance
Liste ações de performance com métricas agregadas.site_id, from, to e os filtros opcionais namespaces
(array), revision e action. Em retorno você recebe um array de linhas de ação,
cada uma com namespace, action, digest, mean (ms), throughput,
error_rate (0–100) e has_npo (se uma query N+1 foi detectada).
Arestas de dependência de serviço
Mapeie relações de tracing distribuído entre ações e serviços.action_edges retorna as arestas upstream (chamadores) e downstream (chamados)
de uma ação em foco. Seu corpo recebe site_id, namespace (no
formato "<service>/<namespace>", como "PublicApi/web"), action, from e
to.
site_edges retorna arestas upstream, downstream e internal para um site em
foco. Seu corpo recebe site_id, from e to.
Em ambos, from é inclusivo e to é exclusivo.
Cada aresta informa o service pareado, count de requisições, error_count, mean (ms)
e durações p_90 / p_95. As arestas de ação também incluem o namespace e a
action do peer, os span kinds caller_kind e callee_kind, e edge_type
(SYNC ou ASYNC).
Eventos lentos
Analise operações lentas dentro de traces, como queries lentas de banco de dados.slow_events retorna até 100 eventos lentos agregados. Seu corpo recebe
site_id, from, to e wanted_attributes. Você também pode adicionar estes
filtros:
span_kind: incluir apenas um tipo de span:Client,Server,Internal,ProducerouConsumer.excluded_attributes: deixar de fora spans que tenham qualquer uma das chaves de atributo listadas.
wanted_attributes nomeia os atributos de span a retornar. Agrupe-os sob nomes
em minúsculas que você escolher, como payload. Cada grupo é Required ou
Optional:
Requiredinclui apenas spans em que pelo menos uma das chaves listadas tem valor.Optionalretorna o valor quando ele está definido, e não filtra spans.
appsignal.library. Ela retorna a biblioteca com que a AppSignal instrumentou o
span, como active_record, e fica vazia para outros spans. Por exemplo,
"system": { "Optional": ["db.system.name", "db.system", "appsignal.library"] }
retorna o sistema de banco de dados quando o span registra um, e a biblioteca
caso contrário. Spans armazenados antes do fim de julho de 2026 a retornam
vazia.
A requisição precisa de pelo menos um grupo Required, ou retorna 400. Esta
requisição lista queries lentas de banco de dados, com o texto da query e o
sistema de banco de dados:
digest, count, mean (ms) e uma pontuação de
impact. Cada grupo em wanted_attributes volta como uma chave própria, como
"payload": "SELECT * FROM users WHERE id = ?".
slow_events/actions lista as ações em que um evento lento aparece. Seu corpo
recebe site_id, from, to e o digest de slow_events. Cada resultado tem
um action_name, namespace e count, além do trace_id e do start_time da
ocorrência mais recente.
Principais eventos por grupo
Classifique os eventos de um ou mais grupos de eventos, como queriesactive_record, por tempo total, duração média ou throughput.
site_id, from, to e groups: pelo menos um grupo de
eventos, como ["active_record", "moped"]. A AppSignal amplia from e to
para buckets inteiros de resolution. order classifica os eventos por
IMPACT (o padrão), MEAN ou THROUGHPUT. limit aceita de 1 a 1.000 linhas
e tem padrão 1.000.
Cada linha tem o digest, o group e o name do evento, como
sql.active_record. Ela tem um title e um body, como o texto da query.
Também tem o count, a duração mean em milissegundos e o impact: o tempo
total gasto, count vezes mean. Alguns eventos são deixados de fora após a
classificação, então podem voltar menos linhas que limit.
Investigar incidentes de erro
Conte os erros de cada incidente e depois veja o que os incidentes têm em comum.tracing/errors conta erros por incidente. Seu corpo recebe site_id, from
e to, e você pode filtrar por namespaces e revision. Cada linha tem um
incident_digest, o namespace e a revision mais recente dele, e um
error_count. A resposta inclui todos os incidentes correspondentes, sem
ordenação. Para encontrar os incidentes com mais erros, ordene as linhas por
error_count.
metadata_distributions detalha incidentes pelos metadados deles, como
hostname. Seu corpo recebe site_id, os incident_digests a incluir, from
e group_by:
KEYlista cada chave de metadados, com ototalde ocorrências e o número de valoresunique.VALUElista os valores da chave que você define emmetadata_key. Em cada linha,keycontém o valor evaluecontém quantas vezes ele ocorre.
to tem como padrão o momento atual. limit aceita de 1 a 1.000 linhas. O
padrão é 10 linhas no modo VALUE, e sem limite no modo KEY.
Para ver os traces por trás de um incidente, passe o digest dele para
traces/errors ou trace/error.