cpra

Continuous Pulse and Recovery Agent
Verifica serviços, envia alertas e executa as ações de recuperação que você configurar.

O CPRa é um agente de monitoramento e recuperação auto-hospedado escrito em Go. Ele executa verificações de integridade nos seus serviços de acordo com uma programação, abre e fecha incidentes com base em limites configuráveis, envia notificações e executa uma ação de recuperação — reiniciar um contêiner, chamar um webhook, reiniciar ou escalar uma carga de trabalho do Kubernetes, reiniciar uma instância EC2, reiniciar uma unidade systemd — quando um serviço falha. Ele é distribuído como um único binário de servidor com um painel somente leitura incorporado, uma API HTTP e o cliente de linha de comando cpractl. É licenciado sob MIT.

Documentação: ziad-hsn.github.io/cpra — início rápido · configuração de monitoramento · drivers · API HTTP · implantação · FAQ

Documentação e desenvolvimento atual

A fonte da documentação inclui referências de desenvolvimento atuais e guias explicitamente datados para revisões anteriores. O site publicado é atualizado separadamente. Versões e disponibilidade identifica esses limites:

• Esta fonte inclui persistência Raft, histórico/SLOs, recursos de gerenciamento criptografados, formulários do painel e fluxos de coleta do SDK/CLI.
• O progresso da implementação registra verificações concluídas e a integração pendente de workers externos e os portões de lançamento.
• O SDK Go documenta os contratos atuais do código-fonte; a qualificação pública da versão do módulo e do consumidor baixado permanece pendente.
• Guias candidatos anteriores descrevem a revisão fixada 410fbfb e não constituem uma qualificação de lançamento para este branch de desenvolvimento.

O plano de entrega rege a publicação. A disponibilidade do código-fonte não estabelece verificação concluída de provedor ou de resistência.

Início rápido

Requer Go 1.25 ou posterior, Make e Python 3 para o workspace de código-fonte abaixo. O repositório já contém os recursos do painel compilados.

O Make cria um bin/cpra-sdk.work ignorado para a aplicação e seus módulos SDK locais, para que o candidato de SDK não publicado possa ser compilado a partir deste checkout. O módulo de exemplo de integrações permanece opcional. Um caminho GOWORK explícito ou GOWORK=off tem precedência; o Make nunca altera o workspace externo selecionado.

make
cp examples/monitors.yaml monitors.yaml
# Set the service address in monitors.yaml.
./bin/cpra -yaml monitors.yaml

Para comandos Go diretos, selecione o workspace explicitamente após make dev-workspace:

GOWORK="$PWD/bin/cpra-sdk.work" go test ./internal/cpractl/cli

As compilações de lançamento oficiais mantêm GOWORK=off e exigem dependências de módulo qualificadas separadamente. Compilações de workspace local não estabelecem a disponibilidade pública do módulo nem a prontidão para lançamento.

O estado é durável por padrão no diretório de estado do usuário da plataforma (cpractl local paths); serviços de sistema Linux usam explicitamente /var/lib/cpra. Mantenha esse diretório entre reinicializações. Um -data-dir explícito substitui a configuração de tempo de execução e o padrão da plataforma. Um ./cpra-data legado exige um caminho explícito ou uma migração com o serviço parado. Use -runtime-config examples/runtime-memory.yaml para uma execução descartável. Persistência e recuperação descreve identidades, resultados desconhecidos e backups completos.

Abra http://localhost:8060 usando as credenciais de API configuradas. A configuração de gerenciamento habilita comandos atuais do SDK, como ./bin/cpractl get monitors; esses comandos usam IDs de recursos estáveis. Configuração ausente ou malformada interrompe a inicialização. Configurações vazias exigem -allow-empty.

O exemplo verifica um endpoint HTTP e grava transições de incidentes em alerts.jsonl. Cada monitor pode especificar um intervalo de verificação, tempo limite, limite de falhas, limite de recuperação, destinos de notificação e uma ação de recuperação. Janelas de manutenção suprimem alertas e recuperação enquanto as verificações continuam; elas usam expressões cron de cinco campos, uma duração e um fuso horário IANA.

Drivers

Função	Compilação padrão	Tags de compilação opcionais
Verificações	HTTP, TCP, ICMP, DNS, UDP, TLS, Docker, alcançabilidade de porta gRPC	redis postgres mysql mongo rabbitmq kafka
Recuperação	Docker, webhook HTTP	kubernetes aws systemd
Alertas	Log, Slack, PagerDuty, e-mail, webhook, Telegram, Discord, Opsgenie, Mattermost, VictorOps, Pushover, Datadog	teams twilio

make BUILD_TAGS='redis postgres kubernetes'

A verificação grpc testa a porta TCP; ela não chama o serviço de integridade gRPC. Verificações UDP exigem um payload e uma resposta. O PagerDuty exige uma chave de roteamento da Events API v2. O e-mail usa um relay SMTP com STARTTLS; a autenticação por nome de usuário/senha SMTP não está implementada.

O warn_days do TLS produz um alerta amarelo e um status de monitor degradado sem iniciar a recuperação; critical_days faz a verificação falhar e segue a política de recuperação normal. A prioridade de emergência do Pushover aceita retry e expire em segundos, com padrões de 60 e 1800. A recuperação do Docker preserva a carência de parada do daemon quando seu tempo limite é omitido.

Verificações do MongoDB exigem uma URI mongodb:// direta. O driver selecionado não consegue limitar a descoberta inicial de mongodb+srv:// pelo prazo da verificação, então o CPRa rejeita esse modo. A recuperação do Kubernetes suporta credenciais por token, certificado e no cluster; plugins de credenciais exec do kubeconfig são rejeitados porque podem ultrapassar o prazo de recuperação.

Acesso

O servidor escuta no loopback por padrão. Outros endereços de bind exigem um token de autenticação. Mantenha o token em um arquivo legível pela conta de serviço: