> ## 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.
# Traces
> Busque performance samples e error traces a partir do terminal e inspecione suas span trees até um único span.
Você pode localizar performance actions e error incidents associados a um trace.
Use os comandos `samples` ou `traces` (aliases) para buscar samples individuais dos dados de tracing do AppSignal. Traces mostram o que aconteceu durante uma request, job ou execução de script, e podem exibir o trace por trás de uma exception.
Liste traces e, em seguida, abra um para visualizar sua span tree e inspecionar os tempos, tags e attributes de um único span.
O comando está disponível como `samples` ou `traces`. `appsignal-cli traces list` e `appsignal-cli samples list` fazem a mesma coisa. Esta página usa `traces` ao longo do texto.
Os traces são obtidos por meio da REST tracing API do AppSignal usando sua conta autenticada, então autentique a CLI primeiro. Veja [Autenticação](/cli/authentication).
## Opções comuns
Todo comando `traces` identifica uma aplicação e usa sua organização padrão, a menos que você indique o contrário:
| Flag | Descrição |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `--app ` | Nome da aplicação (adicione `--environment` quando mais de uma aplicação compartilhar o nome) |
| `--environment ` | Environment, usado com `--app`, como `production` ou `development` |
| `--app-id ` | O ID da aplicação (uma longa string hexadecimal obtida em `appsignal-cli apps list`), no lugar de `--app` e `--environment` |
| `--org ` | Slug da organização (usa o padrão se omitido) |
## Encontrar um trace a partir de um incident
A maioria das investigações começa por um incident, não por um trace ID. Estes passos levam você de um número de incident até a span tree de uma única request, seguindo uma `PaymentDeclinedException` do Laravel em `POST /checkout` (exception incident 9).
### 1. Leia o digest do incident
Error traces são agrupados por um exception digest. Leia o digest a partir do incident, ou copie-o do AppSignal app:
```sh Shell theme={null}
appsignal-cli incidents show --app "MyApp" --environment development \
--number 9 --output json
```
O digest está no campo `digests`:
```json theme={null}
{
"incident": {
"number": 9,
"exceptionName": "App\\Exceptions\\PaymentDeclinedException",
"exceptionMessage": "Card was declined: insufficient_funds (amount $129.99)",
"actionNames": ["POST /checkout"],
"namespace": "Laravel Service/web",
"digests": ["3377052059360943972"]
}
}
```
### 2. Liste os traces para esse digest
Passe o digest para `traces errors`. Cada linha é uma ocorrência capturada:
```sh Shell theme={null}
appsignal-cli traces errors --app "MyApp" --environment development \
--digest 3377052059360943972
```
```
Error traces for digest 3377052059360943972
+----------------------------------+----------+--------------------------+----------------+
| TRACE ID | DURATION | TIME | ACTION |
+----------------------------------+----------+--------------------------+----------------+
| 92240dcdb4face2e36c8ba47372b50f1 | 466.0ms | 2026-06-24T11:30:45.376Z | POST /checkout |
| 964fccaae622462e39c7b2f14238cc5a | 970.0ms | 2026-06-24T11:30:34.867Z | POST /checkout |
| 781e8f5fec07ffa849c5bc5e7b8eaaa2 | 683.0ms | 2026-06-24T11:29:03.529Z | POST /checkout |
+----------------------------------+----------+--------------------------+----------------+
3 error trace(s) found.
```
Copie o trace ID que você quer inspecionar.
### 3. Inspecione o trace
Passe o número do incident e o trace ID para `traces show-incident`:
```sh Shell theme={null}
appsignal-cli traces show-incident --app "MyApp" --environment development \
--number 9 --trace-id 92240dcdb4face2e36c8ba47372b50f1
```
```
Span tree for sample/trace 92240dcdb4face2e36c8ba47372b50f1
POST /checkout [server] 466.0ms 1 event(s) !! App\Exceptions\PaymentDeclinedException span:7a6bfdf173a4b5ed
SELECT * FROM carts WHERE user_id = ? [internal] 7.0ms span:c215afea3041cb8d
SELECT * FROM cart_items WHERE cart_id = ? [internal] 18.0ms span:567513335ff37ff6
stripe.charge [client] 334.0ms span:9b280149985e2272
INSERT INTO orders (...) VALUES (...) [internal] 15.0ms span:a30563643f738120
mail.send [internal] 78.0ms span:966158dc67ebaaa1
Total spans: 6
Error spans: 1
Slowest span: POST /checkout (466.0ms)
```
O `!!` marca o span que gerou a exception: aqui, `POST /checkout` logo após o `stripe.charge` de 334 ms. Para inspecionar um único span por completo, adicione `--span-id` com o valor de seu `span:`. Veja [inspecionar um único span](#inspecionar-um-unico-span).
Estes passos começam a partir de um exception incident. Se você estiver começando de outro ponto, use o comando correspondente:
* **Um performance incident:** `traces incident --number ` lista seus traces sem digest. Veja [para um incident](#para-um-incident).
* **Um namespace e uma action conhecidos:** `traces list --namespace --action `. Veja [para uma action](#para-uma-action).
## Listar traces
Três comandos listam traces, dependendo do ponto de partida: uma performance action, um incident ou um exception digest. Cada um retorna uma tabela de trace IDs que você pode então passar para os comandos de inspeção da próxima seção.
### Para uma action
Liste os performance samples recentes para um namespace e uma action:
```sh Shell theme={null}
appsignal-cli traces list --app "MyApp" --environment development \
--namespace "Laravel Service/web" --action "GET /products"
```
```
Performance samples/traces for Laravel Service/web / GET /products
Time range: 2026-07-02T00:00:00Z to 2026-07-03T00:00:00Z
+----------------------------------+-----------+----------------------+---------------+
| TRACE ID | DURATION | TIME | ACTION |
+----------------------------------+-----------+----------------------+---------------+
| a1b2c3d4e5f60718293a4b5c6d7e8f90 | 1120.0ms | 2026-07-02T14:12:07Z | GET /products |
| 3c4d5e6f708192a3b4c5d6e7f8091a2b | 842.0ms | 2026-07-02T14:03:51Z | GET /products |
| 9f8e7d6c5b4a30291827a6b5c4d3e2f1 | 631.0ms | 2026-07-02T13:58:19Z | GET /products |
+----------------------------------+-----------+----------------------+---------------+
3 sample(s)/trace(s) found.
```
`list` exige `--namespace`, `--action` e uma aplicação (`--app` ou `--app-id`), e aceita estas opções adicionais:
| Flag | Descrição |
| ------------------------ | --------------------------------------------------------------------------- |
| `--namespace ` | Namespace onde pesquisar, ex.: `web`, `background`, `graphql` (obrigatório) |
| `--action ` | Action para buscar traces, ex.: `GET /products` (obrigatório) |
| `--start ` | Horário de início, ex.: `2025-01-15T00:00:00Z` (padrão: 24 horas atrás) |
| `--end ` | Horário de término (padrão: agora) |
| `--min-duration-ms ` | Retorna apenas traces com pelo menos essa duração em milissegundos |
| `--limit ` | Número máximo de traces a retornar (1–100, padrão 25) |
| `--page-all` | Busca todos os traces no intervalo, ignorando `--limit` |
`--namespace` é o [namespace](/application/namespaces) do AppSignal que agrupa a action, geralmente `web`, `background`, `rake`, `runner` ou `graphql`. Sua aplicação também pode definir namespaces personalizados. Se você não tiver certeza a qual namespace uma action pertence, use `traces incident --number `: ele lê os nomes de namespace e action diretamente do performance incident, para que você não precise informá-los.
### Para um incident
Pule a busca por namespace e action e liste os samples por trás de um performance incident pelo seu número:
```sh Shell theme={null}
appsignal-cli traces incident --app "MyApp" --environment development --number 17
```
Se o incident abranger várias actions, os resultados são agrupados por action. Passe `--action` para restringir a busca a uma delas. Além das opções comuns, `incident` aceita:
| Flag | Descrição |
| ------------------------ | ------------------------------------------------------------------ |
| `--number ` | Número do performance incident (obrigatório) |
| `--action ` | Restringe a busca a uma action quando o incident tem várias |
| `--start ` | Horário de início (padrão: 24 horas atrás) |
| `--end ` | Horário de término (padrão: agora) |
| `--min-duration-ms ` | Retorna apenas traces com pelo menos essa duração em milissegundos |
| `--limit ` | Número máximo de traces por action (1–100, padrão 25) |
| `--page-all` | Busca todos os traces de cada action, ignorando `--limit` |
### Error traces para uma exception
Liste os error traces por trás de uma exception, identificada pelo seu digest:
```sh Shell theme={null}
appsignal-cli traces errors --app "MyApp" --environment development \
--digest 3377052059360943972
```
```
Error traces for digest 3377052059360943972
+----------------------------------+----------+--------------------------+----------------+
| TRACE ID | DURATION | TIME | ACTION |
+----------------------------------+----------+--------------------------+----------------+
| 92240dcdb4face2e36c8ba47372b50f1 | 466.0ms | 2026-06-24T11:30:45.376Z | POST /checkout |
+----------------------------------+----------+--------------------------+----------------+
1 error trace(s) found.
```
`errors` exige `--digest` e uma aplicação (`--app` ou `--app-id`), e também aceita `--limit` (1–100, padrão 25) e `--page-all`. Encontre o digest no exception incident na interface do AppSignal, ou use `traces show-incident` na próxima seção para dispensar o digest por completo.
## Inspecionar um trace
Uma vez que você tenha um trace ID, abra-o para ver a span tree: cada span com seu tipo, duração, número de events e qualquer exception, seguido por um resumo. Três comandos fazem isso, correspondentes às três formas de listar o trace.
### A partir de uma action
Mostre um performance trace pelo seu namespace, action e trace ID:
```sh Shell theme={null}
appsignal-cli traces show --app "MyApp" --environment development \
--namespace "Laravel Service/background" --action "ProcessPaymentJob" \
--trace-id 8b75a80874e7c930c7d1d28c96d82e6c
```
```
Span tree for sample/trace 8b75a80874e7c930c7d1d28c96d82e6c
ProcessPaymentJob [consumer] 537.0ms 1 event(s) !! App\Exceptions\PaymentGatewayTimeoutException span:6a1d23690f4aff3d
SELECT * FROM payments WHERE id = ? [internal] 8.0ms span:8988f5f9e1155049
stripe.capture [client] 518.0ms span:f403c766e07bc10e
Total spans: 3
Error spans: 1
Slowest span: ProcessPaymentJob (537.0ms)
```
A indentação mostra a estrutura pai–filho dos spans. Um span que carrega uma exception é marcado com `!!` e o tipo da exception.
### A partir de um exception digest
Mostre um error trace pelo seu digest e trace ID:
```sh Shell theme={null}
appsignal-cli traces show-error --app "MyApp" --environment development \
--digest 3377052059360943972 \
--trace-id 92240dcdb4face2e36c8ba47372b50f1
```
Use os trace IDs retornados por `traces errors` (ou por `traces incident` para um exception incident).
### A partir de um número de incident
Quando você tem um número de incident em vez de um namespace, action ou digest, `show-incident` verifica o incident para você: a partir do número, ele busca o namespace e a action (ou o digest), para que você não precise informá-los. Você ainda escolhe qual trace inspecionar com `--trace-id`, então liste primeiro os traces do incident com `traces incident`:
```sh Shell theme={null}
appsignal-cli traces show-incident --app "MyApp" --environment development \
--number 17 --trace-id a1b2c3d4e5f60718293a4b5c6d7e8f90
```
### Inspecionar um único span
Adicione `--span-id` a qualquer um dos comandos show para imprimir o detalhe completo de um span em vez da tree: seus tempos, status, tags, span attributes, events e resource attributes.
```sh Shell theme={null}
appsignal-cli traces show --app "MyApp" --environment development \
--namespace "Laravel Service/web" --action "GET /products" \
--trace-id a1b2c3d4e5f60718293a4b5c6d7e8f90 \
--span-id 1b2c3d4e5f607182
```
Pegue o span ID a partir do valor `span:` no final de cada linha da span tree. Se o ID não estiver no trace, a CLI lista quais estão disponíveis:
```
Error: Span 1b2c3d4e5f607182 not found in trace a1b2c3d4e5f60718293a4b5c6d7e8f90. Rerun without `--span-id` to see available span IDs.
```
### Dados sensíveis
Por padrão, os comandos show omitem HTTP headers, parâmetros de request, dados de sessão e parâmetros de função. Adicione `--include-sensitive` para exibi-los:
```sh Shell theme={null}
appsignal-cli traces show --app "MyApp" --environment development \
--namespace "Laravel Service/web" --action "GET /products" \
--trace-id a1b2c3d4e5f60718293a4b5c6d7e8f90 \
--span-id 0a1b2c3d4e5f6071 --include-sensitive
```
`--include-sensitive` pode exibir dados pessoais e segredos capturados em uma request. Tenha cuidado ao compartilhar a saída ou canalizá-la para outra ferramenta.
## Intervalo de tempo e paginação
`list`, `incident` e os comandos show de performance olham para trás por 24 horas por padrão. Amplie ou mova a janela com `--start` e `--end` (ISO 8601, por exemplo `2025-01-15T00:00:00Z`). Se um trace for mais antigo que a janela padrão, uma busca por ID informará que ele não foi encontrado: execute novamente com um `--start` anterior.
`--limit` limita uma listagem a até 100 traces (25 por padrão). Para buscar todos os traces no intervalo, use `--page-all`, que ignora `--limit`.
## Saída em JSON
* Adicione a flag global `--output json` (ou `--format json`) para resultados legíveis por máquina.
* Os comandos de listagem (`traces list`, `traces incident`, `traces errors`) retornam um array `traces`.
* Os comandos show (`traces show`, `traces show-error`, `traces show-incident`) retornam o `trace_id` e seus `spans`, mais um único `span` quando você passa `--span-id`.
* Isso se aplica tanto a performance samples quanto a error traces, e se combina com `--page-all` para paginar por todos os resultados.
* Os resultados (o JSON) são escritos em stdout, enquanto as mensagens de status são escritas em stderr, então canalizar a saída para outra ferramenta nunca mistura texto que não seja JSON.
```sh Shell theme={null}
appsignal-cli --output json traces list --app "MyApp" --environment development \
--namespace "Laravel Service/web" --action "GET /products" --page-all
```
## Próximos passos
Rastreou uma request lenta ou um erro até seu trace? Abra os [incidents](/cli/incidents) relacionados para fazer a triagem, ou percorra seus [logs](/cli/logs) para mais contexto.