Skip to content

Service Lifecycle

O Go Overlay gerencia o ciclo de vida completo de cada serviço, desde o início até o encerramento. Compreender os estados dos serviços e suas transições é essencial para diagnosticar problemas e gerenciar seus containers efetivamente.

Service States

Cada serviço no Go Overlay pode estar em um dos seguintes estados:

PENDING

O estado inicial de um serviço quando o Go Overlay inicia. O serviço está aguardando para ser iniciado, mas ainda não foi processado.

Características: - Serviço foi carregado da configuração - Nenhuma ação foi tomada ainda - Aguardando resolução de dependências (se houver)

STARTING

O serviço está em processo de inicialização. O Go Overlay executou o comando do serviço e está aguardando que ele esteja totalmente operacional.

Características: - Processo foi iniciado - PID foi atribuído - Pre-scripts foram executados (se configurados) - Serviço ainda não confirmou estar totalmente operacional

RUNNING

O serviço está operacional e funcionando normalmente. Este é o estado desejado para serviços ativos.

Características: - Processo está em execução - Serviço passou pela fase de inicialização - Respondendo normalmente - Monitoramento ativo de saúde

STOPPING

O serviço está em processo de encerramento graceful. O Go Overlay enviou um sinal de término e está aguardando o serviço encerrar adequadamente.

Características: - SIGTERM foi enviado ao processo - Timeout de shutdown está ativo - Aguardando término graceful - Pos-scripts serão executados após término

STOPPED

O serviço foi encerrado completamente e não está mais em execução.

Características: - Processo terminou - Recursos foram liberados - Pos-scripts foram executados (se configurados) - Estado final para serviços desabilitados ou parados manualmente

FAILED

O serviço encontrou um erro e não conseguiu iniciar ou falhou durante a execução.

Características: - Processo terminou inesperadamente - Exit code não-zero - Pode acionar shutdown do sistema se required = true - Logs devem conter informações sobre a falha

State Transition Diagram

O diagrama abaixo ilustra as transições possíveis entre os estados dos serviços:

stateDiagram-v2
    [*] --> PENDING: Service loaded

    PENDING --> STARTING: Dependencies met,\nstart command executed

    STARTING --> RUNNING: Process started\nsuccessfully
    STARTING --> FAILED: Start failed or\nprocess crashed

    RUNNING --> STOPPING: Shutdown signal\nreceived
    RUNNING --> FAILED: Process crashed or\nexit code non-zero

    STOPPING --> STOPPED: Graceful shutdown\ncompleted
    STOPPING --> STOPPED: Timeout reached,\nSIGKILL sent

    FAILED --> [*]: Service terminated
    STOPPED --> [*]: Service terminated

State Transitions and Triggers

PENDING → STARTING

Trigger: - Todas as dependências do serviço (configuradas via depends_on) estão em estado RUNNING - Delay configurado em wait_after foi cumprido - Go Overlay está pronto para iniciar o serviço

Ações: 1. Executa pre-script (se configurado) 2. Inicia o processo do serviço com o comando especificado 3. Atribui PID ao serviço 4. Inicia monitoramento do processo

STARTING → RUNNING

Trigger: - Processo foi iniciado com sucesso - PID está ativo e respondendo - Nenhuma falha imediata detectada

Ações: 1. Marca serviço como operacional 2. Libera serviços dependentes para iniciar 3. Continua monitoramento de saúde

STARTING → FAILED

Trigger: - Processo falhou ao iniciar - Exit code não-zero imediatamente após início - Pre-script falhou

Ações: 1. Registra erro nos logs 2. Se required = true, inicia shutdown do sistema 3. Libera recursos alocados

RUNNING → STOPPING

Trigger: - Comando de shutdown recebido (SIGTERM para o supervisor) - Comando CLI restart executado - Serviço dependente crítico falhou

Ações: 1. Envia SIGTERM ao processo do serviço 2. Inicia timer de timeout (service_shutdown_timeout) 3. Aguarda término graceful

RUNNING → FAILED

Trigger: - Processo terminou inesperadamente - Exit code não-zero - Processo crashou

Ações: 1. Registra falha nos logs com exit code 2. Se required = true, inicia shutdown do sistema 3. Executa pos-script (se configurado)

STOPPING → STOPPED

Trigger: - Processo terminou gracefully dentro do timeout - OU timeout expirou e SIGKILL foi enviado

Ações: 1. Executa pos-script (se configurado) 2. Libera recursos 3. Marca serviço como encerrado

Monitoring Service States

Você pode monitorar o estado atual de todos os serviços usando o CLI:

# Ver status de todos os serviços
go-overlay status

# Listar serviços com seus estados
go-overlay list

Exemplo de output:

Service: nginx
Status: RUNNING
PID: 1234

Service: mariadb
Status: RUNNING
PID: 1235

Service: redis
Status: STARTING
PID: 1236

Best Practices

1. Handle Signals Properly

Certifique-se de que seus serviços respondem adequadamente a SIGTERM para permitir shutdown graceful:

// Exemplo em Go
sigChan := make(chan os.Signal, 1)
signal.Notify(sigChan, syscall.SIGTERM, syscall.SIGINT)

go func() {
    <-sigChan
    // Cleanup logic here
    os.Exit(0)
}()

2. Set Appropriate Timeouts

Configure timeouts adequados para seus serviços baseado no tempo necessário para shutdown graceful:

[timeouts]
service_shutdown_timeout = "30s"  # Ajuste conforme necessário

3. Use Required Flag Wisely

Marque apenas serviços verdadeiramente críticos como required = true:

[[services]]
name = "database"
command = "/usr/bin/mysqld"
required = true  # Sistema encerra se este serviço falhar

4. Monitor Logs

Sempre verifique os logs quando um serviço entra em estado FAILED:

# Logs do Go Overlay mostrarão detalhes da falha
docker logs <container-id>

5. Test State Transitions

Teste diferentes cenários de transição de estado durante desenvolvimento:

  • Shutdown graceful
  • Falhas de serviço
  • Timeouts
  • Dependências falhando

Troubleshooting

Service Stuck in STARTING

Possíveis causas: - Processo não está iniciando corretamente - Pre-script está travado - Dependências não foram satisfeitas

Solução: - Verifique logs do serviço - Teste o comando manualmente - Verifique configuração de dependências

Service Goes to FAILED Immediately

Possíveis causas: - Comando incorreto ou não encontrado - Permissões insuficientes - Configuração inválida do serviço

Solução: - Verifique o comando e argumentos - Verifique permissões do usuário configurado - Teste o comando fora do supervisor

Service Won't Stop (Stuck in STOPPING)

Possíveis causas: - Serviço não responde a SIGTERM - Timeout muito curto - Processo filho não está sendo encerrado

Solução: - Aumente service_shutdown_timeout - Implemente handler de SIGTERM no serviço - Verifique processos filhos