Incidents - AppSignal Documentation

A CLI permite que você trabalhe com incidentes sem abrir a interface web. Você pode listar incidentes de todos os tipos ou por tipo, restringi-los por estado, namespace ou ação, abrir os detalhes de um único incidente, atualizar seu estado, severidade ou frequência de notificação, e gerenciar as notas dele. Todo comando incidents tem como alvo uma aplicação, identificada por nome e ambiente (--app "MyApp" --environment production) ou por ID (--app-id <APP_ID>, o longo ID hexadecimal do app obtido em appsignal-cli apps list). A flag --environment só é necessária quando várias aplicações compartilham o mesmo nome. Adicione --org para sobrescrever sua organização padrão. Veja Aplicações e organizações para saber como as aplicações são identificadas.

Listar incidentes

Para listar incidentes recentes de todos os tipos de uma aplicação:

Shell

appsignal-cli incidents list --app "MyApp" --environment production --limit 5

Por padrão, os comandos de listagem retornam os 10 incidentes mais recentes, ordenados pela atividade mais recente.

Listar por tipo

Três comandos restringem os resultados a um único tipo de incidente:

Shell

# Exception incidents
appsignal-cli incidents list-exceptions --app "MyApp" --environment production

# Performance traces
appsignal-cli incidents list-performance --app "MyApp" --environment production

# Anomaly detection incidents
appsignal-cli incidents list-anomalies --app "MyApp" --environment production

Filtrar e pesquisar

Os comandos de listagem compartilham um conjunto de filtros:

Flag	Descrição
`--state <STATE>`	Filtra por estado: `OPEN`, `CLOSED` ou `WIP`
`--order <ORDER>`	Ordena por `LAST` (atividade mais recente, o padrão) ou `ID` (ordem de criação)
`--limit <N>`	Número máximo de resultados (padrão: 10)
`--offset <N>`	Número de resultados a pular, para paginação

incidents list, list-exceptions e list-performance também aceitam:

Flag	Descrição
`--namespaces <list>`	Filtra por namespaces, separados por vírgula (ex.: `web,background`)
`--action <name>`	Filtra pelo nome da ação (ex.: `UsersController#show`)
`--query <text>`	Pesquisa incidentes de exceção pelo nome ou mensagem, ou incidentes de desempenho pelo nome da ação (apenas `list-exceptions` e `list-performance`)

Para encontrar erros de timeout:

Shell

appsignal-cli incidents list-exceptions --app "MyApp" --environment production --query "TimeoutError"

Você pode passar vários filtros em um único comando, e todos serão aplicados em conjunto para restringir os resultados. Por exemplo, listar apenas as exceções abertas no namespace web:

Shell

appsignal-cli incidents list-exceptions --app "MyApp" --environment production \
  --state OPEN --namespaces web

Os comandos de listagem retornam incidentes recentes, então incidentes mais antigos podem não aparecer mesmo que ainda estejam abertos. Para abrir um incidente específico independentemente da idade, use incidents show com seu número.

Mostrar um incidente

Para ver os detalhes completos de um único incidente, passe seu número:

Shell

appsignal-cli incidents show --number 42 --app "MyApp" --environment production

Para incidentes de exception, show também lista as causas dos erros a partir dos dados de trace do incidente. Às vezes um erro envolve outro, como um timeout que aparece como um erro genérico de requisição. Quando isso acontece, as causas subjacentes aparecem ao lado da exception de nível superior, para que você possa encontrar a causa raiz sem abrir um trace na interface web.

Atualizar um incidente

Atualize o estado, a severidade, a frequência de notificação, os responsáveis ou a descrição de um incidente pelo número:

Shell

appsignal-cli incidents update --number 42 --app "MyApp" --environment production --state CLOSED

Flag	Descrição
`--state <STATE>`	Novo estado: `OPEN`, `CLOSED` ou `WIP`
`--severity <SEV>`	Nova severidade: `UNTRIAGED`, `CRITICAL`, `HIGH`, `LOW`, `NONE` ou `INFORMATIONAL`
`--notification-frequency <FREQ>`	Nova frequência de notificação: `ALWAYS`, `NEVER`, `FIRST_IN_DEPLOY`, `FIRST_AFTER_CLOSE`, `NTH_IN_HOUR` ou `NTH_IN_DAY`
`--notification-threshold <N>`	Número da ocorrência que envia uma notificação `NTH_IN_HOUR` ou `NTH_IN_DAY`
`--assign <NAMES_OR_IDS>`	Nomes de usuários ou IDs a adicionar como responsáveis, separados por vírgula
`--assign-me`	Atribui o incidente ao seu usuário autenticado
`--unassign <NAMES_OR_IDS>`	Nomes de usuários ou IDs a remover dos responsáveis, separados por vírgula
`--description <text>`	Nova descrição

Para alterar vários incidentes de uma vez, passe uma lista de números separada por vírgulas. Atualizações em massa atualmente suportam apenas --state:

Shell

appsignal-cli incidents update --number 41,42,43 --app "MyApp" --environment production --state CLOSED

Definir a frequência de notificação

--notification-frequency controla quando o AppSignal notifica você sobre as ocorrências de um incidente. Ela usa as mesmas opções da configuração de notificação na interface do AppSignal, descrita em Configurações de notificação:

Valor	Configuração na interface
`ALWAYS`	Every Occurrence
`FIRST_IN_DEPLOY`	First in Deploy (o padrão para novos incidentes de erro)
`FIRST_AFTER_CLOSE`	First After Close
`NEVER`	Never Notify
`NTH_IN_HOUR`	Every Nth per Hour
`NTH_IN_DAY`	Every Nth per Day

Para ser notificado apenas quando um incidente fechado ocorrer novamente:

Shell

appsignal-cli incidents update --number 42 --app "MyApp" --environment production \
  --notification-frequency FIRST_AFTER_CLOSE

NTH_IN_HOUR e NTH_IN_DAY usam --notification-threshold para definir qual ocorrência envia a notificação. Passe-o junto com a frequência. Para ser notificado a cada décima ocorrência por dia:

Shell

appsignal-cli incidents update --number 42 --app "MyApp" --environment production \
  --notification-frequency NTH_IN_DAY --notification-threshold 10

Atribuir um incidente

Para atribuir um incidente a você mesmo, use --assign-me. Não é necessário um ID de usuário:

Shell

appsignal-cli incidents update --number 42 --app "MyApp" --environment production --assign-me

Para atribuir a outras pessoas, passe seus nomes ou IDs de usuário para --assign, separados por vírgula. Um ID de usuário é uma longa string hexadecimal. Encontre nomes e IDs com apps resources users, que lista o nome, ID e e-mail de cada usuário:

Shell

appsignal-cli apps resources users --app "MyApp" --environment production

Em seguida, passe um ou mais para --assign:

Shell

appsignal-cli incidents update --number 42 --app "MyApp" --environment production \
  --assign <NAME_OR_ID>

Para remover responsáveis, passe seus nomes ou IDs para --unassign da mesma forma.

Notas

Notas registram o que você descobriu sobre um incidente e permanecem com ele, para que quem abrir o incidente em seguida tenha o contexto. Você pode adicionar uma nota, listar as notas de um incidente e editar ou remover as que você escreveu.

Adicionar uma nota

Shell

appsignal-cli incidents add-note --number 42 --app "MyApp" --environment production \
  --content "Root cause identified."

O conteúdo da nota suporta Markdown, então uma nota mais longa pode conter títulos, listas, código e links:

Shell

appsignal-cli incidents add-note --number 42 --app "MyApp" --environment production \
  --content $'## Investigation\n\n- Root cause: connection pool exhaustion\n- Fix: raised the pool limit in `database.yml`'

A formatação $'...' transforma \n em uma quebra de linha real no Bash e no Zsh. Em um shell sem esse recurso, passe o conteúdo como uma string multilinha entre aspas.

Listar notas

Editar ou excluir uma nota exige seu ID. Liste as notas de um incidente para encontrá-lo, junto com o autor, a origem, o timestamp e se você pode editá-la ou excluí-la:

Shell

appsignal-cli incidents list-notes --number 42 --app "MyApp" --environment production

Atualizar ou excluir uma nota

Passe o ID da nota obtido em list-notes. update-note substitui o conteúdo da nota:

Shell

appsignal-cli incidents update-note --number 42 --app "MyApp" --environment production \
  --id <NOTE_ID> --content "Root cause confirmed: connection pool exhaustion."

delete-note a remove:

Shell

appsignal-cli incidents delete-note --number 42 --app "MyApp" --environment production \
  --id <NOTE_ID>

Você só pode atualizar e excluir as notas que escreveu. list-notes marca isso nas colunas CAN EDIT e CAN DELETE.

Saída em JSON

Como todo comando, os comandos de incidentes aceitam a flag global --output json (ou --format json), que retorna uma saída legível por máquina para scripts e agentes de IA:

Shell

appsignal-cli --output json incidents list-exceptions --app "MyApp" --environment production --state OPEN

Para retornar um único incidente como JSON, restrinja pelo número com incidents show:

Shell

appsignal-cli --output json incidents show --number 42 --app "MyApp" --environment production

Próximos passos

Os incidentes mostram o que está falhando. Para ver os traces individuais por trás de um deles, busque seus traces pelo número do incidente. Para ver as linhas de log ao redor, acompanhe ou pesquise seus logs a partir do terminal.

​Listar incidentes

​Listar por tipo

​Filtrar e pesquisar

​Mostrar um incidente

​Atualizar um incidente

​Definir a frequência de notificação

​Atribuir um incidente

​Notas

​Adicionar uma nota

​Listar notas

​Atualizar ou excluir uma nota

​Saída em JSON

​Próximos passos

Listar incidentes

Listar por tipo

Filtrar e pesquisar

Mostrar um incidente

Atualizar um incidente

Definir a frequência de notificação

Atribuir um incidente

Notas

Adicionar uma nota

Listar notas

Atualizar ou excluir uma nota

Saída em JSON

Próximos passos