Pular para o conteúdo principal
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

CampoTipoObrigatórioDescrição
site_idsstring[]SimSites a serem consultados.
paginationobjectSimConfigurações de paginação. Defina cursor como Time ou Duration.
digestsstring[]NãoFiltrar por digests de trace.
action_namestringNãoFiltrar por nome da ação.
namespacestringNãoFiltrar por namespace.
querystringNãoQuery de busca de texto livre.
durationnumber (ms)NãoFiltro de duração mínima.
fromstring (ISO 8601)NãoInício do intervalo de tempo.
tostring (ISO 8601)NãoFim do intervalo de tempo.
ttlnumberNãoLimite 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:
CampoTipoDescrição
trace_idstringIdentificador de todo o trace.
span_idstringIdentificador do span raiz.
site_idstringSite a que o trace pertence.
namespacestringNamespace, como web ou background.
action_namestringNome da ação, como POST /api/users.
revisionstringRevisão de deploy ativa quando registrado.
timestring (ISO 8601)Quando o trace terminou.
durationnumberDuração total em milissegundos.
tagsobjectTags definidas pelo usuário a partir de atributos de span.
has_npobooleanSe 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.