Consultando traces - AppSignal Documentation

Leia dados de tracing distribuído com a API pública (V2): liste traces de performance e erro, busque os spans de um único trace, inspecione ações agregadas e dependências de serviço, e analise eventos lentos. Todos os endpoints autenticam com seu token pessoal de API. Os endpoints de trace usam um array site_ids para que possam buscar em vários sites em uma única requisição. A maioria dos endpoints de listagem e detalhe compartilha o corpo TracesQuery e retorna resumos de trace ou spans, descritos no final desta página.

Localizar um trace

Encontre as ações de performance e os incidentes de erro em que um trace aparece, entre sites.

POST /api/v2/tracing/locator

O corpo da requisição recebe site_ids (um array de strings) e trace_id (uma string). Em retorno, você obtém um TraceLocation com entradas performance (site_id, namespace, action_name) e entradas errors (site_id, incident_number, exception_name).

Obter os spans de um trace

Retorna cada span de um trace.

POST /api/v2/tracing/trace

O corpo da requisição recebe site_ids (um array de strings) e trace_id (uma string), e retorna um array de spans.

{
  "site_ids": ["YOUR-SITE-ID"],
  "trace_id": "YOUR-TRACE-ID"
}

Os endpoints POST /api/v2/tracing/trace/performance e POST /api/v2/tracing/trace/error retornam os spans de um trace de performance ou erro usando o corpo TracesQuery.

Listar traces

Liste traces de performance ou erro.

POST /api/v2/tracing/traces/performance
POST /api/v2/tracing/traces/errors

Ambos recebem o corpo TracesQuery e retornam um array de resumos de trace.

{
  "site_ids": ["YOUR-SITE-ID"],
  "action_name": "POST /api/users",
  "namespace": "web",
  "from": "2026-06-22T00:00:00Z",
  "to": "2026-06-22T23:59:59Z",
  "pagination": { "per_page": 50, "order": "DESC", "cursor": "Time" }
}

pagination recebe per_page, order e uma chave cursor. Defina cursor como Time para paginar por horário do trace, ou Duration para paginar pela duração total do trace.

TracesQuery

Campo	Tipo	Obrigatório	Descrição
`site_ids`	string[]	Sim	Sites a serem consultados.
`pagination`	object	Sim	Configurações de paginação. Defina `cursor` como `Time` ou `Duration`.
`digests`	string[]	Não	Filtrar por digests de trace.
`action_name`	string	Não	Filtrar por nome da ação.
`namespace`	string	Não	Filtrar por namespace.
`query`	string	Não	Query de busca de texto livre.
`duration`	number (ms)	Não	Filtro de duração mínima.
`from`	string (ISO 8601)	Não	Início do intervalo de tempo.
`to`	string (ISO 8601)	Não	Fim do intervalo de tempo.
`ttl`	number	Não	Limite de retenção em segundos.

Listar ações de performance

Liste ações de performance com métricas agregadas.

POST /api/v2/tracing/actions

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.

POST /api/v2/tracing/action_edges
POST /api/v2/tracing/site_edges

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. 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, action, span kinds e edge_type (SYNC ou ASYNC) do peer.

Eventos lentos

Analise operações lentas dentro de traces, como queries lentas de banco de dados.

POST /api/v2/tracing/slow_events
POST /api/v2/tracing/slow_events/actions

slow_events retorna eventos lentos agregados. Seu corpo recebe site_id, from, to, um span_kind opcional, wanted_attributes, excluded_attributes e um limit (padrão 100). Cada resultado tem um digest, count, mean (ms), score de impact e attributes. slow_events/actions lista as ações em que um evento lento aparece, por digest. Seu corpo recebe site_id, from, to e digest. Cada resultado tem um action_name, namespace, count, trace_id e start_time.

Campos do resumo de trace

Os endpoints de listagem retornam resumos de trace com estes campos:

Campo	Tipo	Descrição
`trace_id`	string	Identificador de todo o trace.
`span_id`	string	Identificador do span raiz.
`site_id`	string	Site a que o trace pertence.
`namespace`	string	Namespace, como `web` ou `background`.
`action_name`	string	Nome da ação, como `POST /api/users`.
`revision`	string	Revisão de deploy ativa quando registrado.
`time`	string (ISO 8601)	Quando o trace terminou.
`duration`	number	Duração total em milissegundos.
`tags`	object	Tags definidas pelo usuário a partir de atributos de span.
`has_npo`	boolean	Se uma query N+1 foi detectada.

Campos do span

Os endpoints de detalhe de trace retornam spans. Cada span inclui timing (start_time, end_time, duration em ms), identidade (trace_id, span_id, parent_span_id, digest) e contexto (service_name, namespace, revision, action_name, span_name, span_kind, scope_name, scope_version). O status é reportado com status_code (como OK ou ERROR) e status_message. Os detalhes estruturados são retornados como objetos e arrays: resource_attributes e span_attributes (objetos), events (com arrays events.timestamp, events.name e events.attributes) e links (com arrays links.trace_id, links.span_id, links.trace_state e links.attributes). subtrace_root indica se o span inicia uma fronteira de serviço separada.

​Localizar um trace

​Obter os spans de um trace

​Listar traces

​TracesQuery

​Listar ações de performance

​Arestas de dependência de serviço

​Eventos lentos

​Campos do resumo de trace

​Campos do span