Pular para o conteúdo principal
Leia dados de tracing distribuído com a API pública (V2). Todos os endpoints autenticam com seu token pessoal de API. Esta página explica como os endpoints de tracing se encaixam. Para todos os campos de cada requisição e resposta, veja a referência dos endpoints de tracing. Alguns endpoints recebem um array 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.
O corpo da requisição recebe 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.
O corpo da requisição recebe 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.
Mais dois endpoints retornam os spans de um trace sem precisar do ID dele:
  • POST /api/v2/tracing/trace/performance recebe um action_name e um namespace.
  • POST /api/v2/tracing/trace/error recebe os digests de um incidente de erro.
Ambos retornam o trace correspondente mais recente. Para buscar um específico, adicione o trace_id dele.

Listar traces

Liste traces de performance ou erro.
Os dois endpoints recebem filtros diferentes:
  • traces/performance precisa de um action_name e um namespace. Adicione duration_ms para listar apenas traces com pelo menos essa duração. Adicione from e to para definir um intervalo de tempo.
  • traces/errors precisa dos digests dos incidentes de erro. Ele não tem intervalo de tempo.
Ambos aceitam uma 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: ASC ou DESC.
  • cursor: { "time": null } para ordenar pelo horário do trace, ou { "duration": null } para ordenar pela duração do trace. null começa da primeira página.
Cada trace na resposta tem um trace_id, o time em que o trace começou e a duration total dele em milissegundos.
Para filtrar por uma tag que contém um ID completo, use =, como em tag.request_id=<id>. Um : é uma correspondência de substring muito mais lenta: ele lê todos os spans com essa tag no intervalo de tempo. Se uma requisição assim receber 429 e o valor for um UUID, a suggestion da resposta mostra a forma com =.

Buscar traces

Busque dados de erros e de performance em vários sites, por ação, exceção, tag ou mensagem.
O corpo precisa de 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: e tag: correspondem exatamente a um campo.
  • message: corresponde a uma frase de palavras inteiras, sem diferenciar maiúsculas e minúsculas.
Coloque entre aspas os valores que contêm espaços. Para restringir os resultados, adicione um 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.
O corpo da requisição recebe 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, Producer ou Consumer.
  • 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:
  • Required inclui apenas spans em que pelo menos uma das chaves listadas tem valor.
  • Optional retorna o valor quando ele está definido, e não filtra spans.
Quando um grupo lista várias chaves, ele retorna o valor da primeira chave que tiver um. Além de chaves de atributo de span, um grupo pode listar 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:
Cada resultado tem um 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 queries active_record, por tempo total, duração média ou throughput.
O corpo recebe 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:
  • KEY lista cada chave de metadados, com o total de ocorrências e o número de valores unique.
  • VALUE lista os valores da chave que você define em metadata_key. Em cada linha, key contém o valor e value conté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.