Traces - AppSignal Documentation

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.

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 <name>`	Nome da aplicação (adicione `--environment` quando mais de uma aplicação compartilhar o nome)
`--environment <env>`	Environment, usado com `--app`, como `production` ou `development`
`--app-id <id>`	O ID da aplicação (uma longa string hexadecimal obtida em `appsignal-cli apps list`), no lugar de `--app` e `--environment`
`--org <slug>`	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:

Shell

appsignal-cli incidents show --app "MyApp" --environment development \
  --number 9 --output json

O digest está no campo digests:

{
  "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:

Shell

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:

Shell

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. 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 <N> lista seus traces sem digest. Veja para um incident.
Um namespace e uma action conhecidos: traces list --namespace <name> --action <name>. Veja 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:

Shell

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 <name>`	Namespace onde pesquisar, ex.: `web`, `background`, `graphql` (obrigatório)
`--action <name>`	Action para buscar traces, ex.: `GET /products` (obrigatório)
`--start <ISO8601>`	Horário de início, ex.: `2025-01-15T00:00:00Z` (padrão: 24 horas atrás)
`--end <ISO8601>`	Horário de término (padrão: agora)
`--min-duration-ms <ms>`	Retorna apenas traces com pelo menos essa duração em milissegundos
`--limit <N>`	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 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 <N>: 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:

Shell

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>`	Número do performance incident (obrigatório)
`--action <name>`	Restringe a busca a uma action quando o incident tem várias
`--start <ISO8601>`	Horário de início (padrão: 24 horas atrás)
`--end <ISO8601>`	Horário de término (padrão: agora)
`--min-duration-ms <ms>`	Retorna apenas traces com pelo menos essa duração em milissegundos
`--limit <N>`	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:

Shell

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:

Shell

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:

Shell

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:

Shell

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.

Shell

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:

Shell

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.

Shell

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 relacionados para fazer a triagem, ou percorra seus logs para mais contexto.

​Opções comuns

​Encontrar um trace a partir de um incident

​1. Leia o digest do incident

​2. Liste os traces para esse digest

​3. Inspecione o trace

​Listar traces

​Para uma action

​Para um incident

​Error traces para uma exception

​Inspecionar um trace

​A partir de uma action

​A partir de um exception digest

​A partir de um número de incident

​Inspecionar um único span

​Dados sensíveis

​Intervalo de tempo e paginação

​Saída em JSON

​Próximos passos

Opções comuns

Encontrar um trace a partir de um incident

1. Leia o digest do incident

2. Liste os traces para esse digest

3. Inspecione o trace

Listar traces

Para uma action

Para um incident

Error traces para uma exception

Inspecionar um trace

A partir de uma action

A partir de um exception digest

A partir de um número de incident

Inspecionar um único span

Dados sensíveis

Intervalo de tempo e paginação

Saída em JSON

Próximos passos