> 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/opere/monitoramento-e-alertas.md).

# Monitoramento e alertas

O que acompanhar em produção, onde cada sinal aparece e o que fazer quando ele dispara.

Esta página é para quem opera a aplicação.

## 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](/opere/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, processos de menos para o volume, ou todas as vagas ocupadas: cada processo processa até `SKAIL_MAX_PARALLEL_TASKS` execuções ao mesmo tempo, 1 por padrão | Monitor, estado Na fila                          | Conferir se a aplicação está rodando com o `SKAIL_WORKLOAD` certo; aumentar `SKAIL_MAX_PARALLEL_TASKS` ou escalar réplicas. Ver [Variáveis de ambiente do runtime](/referencia/variaveis-de-ambiente-do-runtime.md) |
| `Unauthenticated` / `PermissionDenied` no log do runtime                                                       | Chave ou namespace errados ou revogados                                                                                                                                    | Log da aplicação                                 | Ver [Chaves](/opere/configurar-e-hospedar/chaves.md)                                                                                                                                                                |
| `SkailNonDeterministicException` (C#) ou `SkailNonDeterministicError` (TypeScript) 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](/opere/deploy-sem-quebrar-execucoes.md), cenário C                                                                                                                  |
| Runtime não conecta ao skail                                                                                   | Endereço, rede, ou indisponibilidade                                                                                                                                       | Log da aplicação                                 | Conferir `SKAIL_SIDECAR`; ver [Suporte e status](/opere/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 mesmo trace inclui o disparo, o skail e a sua aplicação. O destino é o skail, que alimenta o Monitor. Com `SkailContext.Current.TaskId` no escopo dos logs, você relaciona o log, o trace e o Monitor da mesma execução. Ver [Como observar execuções](/construa/como-fazer/observar-execucoes-monitor-otlp-e-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

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><i class="fa-screwdriver-wrench">:screwdriver-wrench:</i></td><td><strong>Troubleshooting</strong></td><td>Para o diagnóstico de cada sintoma.</td><td><a href="/opere/troubleshooting.md">Troubleshooting</a></td></tr><tr><td><i class="fa-display">:display:</i></td><td><strong>Monitor</strong></td><td>Para a referência da tela.</td><td><a href="/referencia/portal/monitor.md">Monitor</a></td></tr><tr><td><i class="fa-circle-check">:circle-check:</i></td><td><strong>Garantias de execução</strong></td><td>Para o que esperar do sistema.</td><td><a href="/referencia/garantias/garantias-de-execucao.md">Garantias de execução</a></td></tr></tbody></table>