> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Consultando traces

Leia dados de tracing distribuído com a [API pública (V2)](/api/v2/overview): 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](#trace-summary-fields) ou [spans](#span-fields), 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.

<CodeGroup>
  ```shell Endpoint theme={null}
  POST /api/v2/tracing/locator
  ```
</CodeGroup>

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.

<CodeGroup>
  ```shell Endpoint theme={null}
  POST /api/v2/tracing/trace
  ```
</CodeGroup>

O corpo da requisição recebe `site_ids` (um array de strings) e `trace_id` (uma string),
e retorna um array de [spans](#span-fields).

<CodeGroup>
  ```json body.json theme={null}
  {
    "site_ids": ["YOUR-SITE-ID"],
    "trace_id": "YOUR-TRACE-ID"
  }
  ```
</CodeGroup>

Os endpoints `POST /api/v2/tracing/trace/performance` e `POST /api/v2/tracing/trace/error`
retornam os [spans](#span-fields) de um trace de performance ou erro usando
o corpo [`TracesQuery`](#tracesquery).

## Listar traces

Liste traces de performance ou erro.

<CodeGroup>
  ```shell Endpoints theme={null}
  POST /api/v2/tracing/traces/performance
  POST /api/v2/tracing/traces/errors
  ```
</CodeGroup>

Ambos recebem o corpo [`TracesQuery`](#tracesquery) e retornam um array de [resumos
de trace](#trace-summary-fields).

<CodeGroup>
  ```json body.json theme={null}
  {
    "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" }
  }
  ```
</CodeGroup>

`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.

<CodeGroup>
  ```shell Endpoint theme={null}
  POST /api/v2/tracing/actions
  ```
</CodeGroup>

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.

<CodeGroup>
  ```shell Endpoints theme={null}
  POST /api/v2/tracing/action_edges
  POST /api/v2/tracing/site_edges
  ```
</CodeGroup>

`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.

<CodeGroup>
  ```shell Endpoints theme={null}
  POST /api/v2/tracing/slow_events
  POST /api/v2/tracing/slow_events/actions
  ```
</CodeGroup>

`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.