> For the complete documentation index, see [llms.txt](https://docs.skail.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skail.dev/operar/monitoramento-e-alertas.md).

# Monitoramento e alertas

O que acompanhar em produção, onde cada sinal aparece e o que fazer quando ele dispara. Para quem opera a aplicação, não para quem escreve as functions.

## Quando você precisa disto

Ao colocar o primeiro fluxo em produção. Defina os sinais abaixo antes do primeiro incidente, não durante.

## Os sinais que importam

| Sinal                                                        | O que indica                                             | Onde ver                                         | Ação                                                                                                                                            |
| ------------------------------------------------------------ | -------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Execuções em falha                                           | Esgotaram as tentativas; precisam de intervenção         | Monitor, estado Falha                            | Ler a exceção, corrigir a causa (dado, serviço externo, código), retomar. Ver [Retomada manual](/operar/retomada-manual-de-execucoes-falhas.md) |
| Aguardando evento há mais tempo que o prazo esperado         | O fire não está chegando, ou nome e instance id divergem | Monitor, estado Aguardando evento, com nome e id | Comparar com o que o sistema que dispara envia; conferir o webhook do parceiro                                                                  |
| Commands com tentativas altas (que acabam concluindo)        | Uma integração está degradando                           | Monitor, linha do tempo (tentativas por command) | Investigar o serviço externo antes que vire falha                                                                                               |
| Tempo entre trigger e início crescendo                       | Aplicação fora, ou com instâncias de menos para o volume | Monitor, estado Na fila                          | Conferir se a aplicação está rodando com o `SKAIL_WORKLOAD` certo; escalar réplicas                                                             |
| `Unauthenticated` / `PermissionDenied` no log do runtime     | Chave ou namespace errados ou revogados                  | Log da aplicação                                 | Ver [Chaves](/operar/chaves-criar-rotacionar-revogar.md)                                                                                        |
| `SkailNonDeterministicException` em retomadas após um deploy | Fluxo alterado com execuções em andamento                | Monitor (falhas) e log                           | Ver [Deploy sem quebrar execuções em andamento](/operar/deploy-sem-quebrar-execucoes-em-andamento.md), caminho C                                |
| Runtime não conecta ao skail                                 | Endereço, rede, ou indisponibilidade                     | Log da aplicação                                 | Conferir `SKAIL_SIDECAR`; ver [Suporte e status](/operar/suporte-e-status.md)                                                                   |

## O que alertar

Falhas: qualquer execução em falha em produção merece alerta; o volume normal é zero. Esperas vencidas: uma execução aguardando evento além do prazo de negócio (o `WhenAny` com `Delay` já trata isso no fluxo; o alerta é para quem esqueceu o prazo, ou para prazos longos que você quer acompanhar antes). Fila: execuções em Na fila por mais de alguns minutos. Autenticação: qualquer ocorrência.

Monte o alerta a partir de duas fontes: o Monitor e os logs da sua aplicação, que o seu stack de observabilidade já coleta. Um alerta de "log com `Unauthenticated`" e um de "nenhuma execução iniciada em X minutos em horário comercial" cobrem os casos mais graves com o que você já tem.

## Telemetria

O runtime exporta spans por function e command via OpenTelemetry, sob o `traceparent` recebido no trigger; se o seu sistema que dispara propaga `traceparent`, o trace atravessa o skail de ponta a ponta. O destino é o skail, que alimenta o Monitor. Logs com `SkailContext.Current.TaskId` no escopo ligam os três lugares. Ver [Como observar execuções](/construir/testar-depurar-e-observar/como-observar-execucoes-monitor-otlp-logs.md).

## Rotina sugerida

Diária: Monitor filtrado por Falha e por Aguardando evento além do prazo. Semanal: commands com mais tentativas, para ver integrações degradando; versões antigas de workload que ainda têm execuções, para saber quando podem ser despublicadas. Após cada deploy: primeiras retomadas na versão antiga e primeiras execuções na nova.

## Próximos passos

[Troubleshooting](/operar/troubleshooting.md) para o diagnóstico de cada sintoma. [Monitor](/construir/portal/monitor.md) para a referência da tela. [Garantias de execução](/aprender/garantias/garantias-de-execucao.md) para o que esperar do sistema.