Status do Sistema & Saúde da API¶
Arquivos Referenciados Neste Documento - status.py - app.py - main.py - config.py - db.py - watchdog.py - pipeline.py - scan.py - status.json
Tabela de Conteúdo¶
- Introdução
- Estrutura do Projeto
- Componentes Principais
- Visão Geral da Arquitetura
- Análise Detalhada dos Componentes
- Análise de Dependências
- Considerações de Desempenho
- Guia de Solução de Problemas
- Conclusão
- Apêndices
Introdução¶
Este documento fornece documentação detalhada da API para monitoramento do sistema e verificação de saúde de Nexo. Ele aborda: - Verificações de saúde para status do aplicativo, conectividade com o banco de dados e disponibilidade do serviço - Coleta de métricas do sistema, incluindo uso de CPU, consumo de memória, espaço em disco e status da fila de processamento - Pontos de monitoramento da pipeline que mostram o progresso da varredura, taxas de processamento e identificação de gargalos - Resumo da configuração, informações de versão e status de dependência - Atualizações em tempo real por meio de conexões WebSocket para dashboards ao vivo - Exemplos para automação, integração de alertas e configuração de monitoramento de desempenho - Orientações sobre agregação de métricas, retenção de dados históricos e padrões de integração de dashboards
O objetivo é permitir que operadores e desenvolvedores monitorem a saúde e o desempenho da pipeline de descoberta de vídeo de forma confiável e integrem com sistemas de observabilidade externos.
Estrutura do Projeto¶
As funcionalidades de monitoramento e saúde são implementadas principalmente na camada de serviço: - Rotas que expõem pontos de extremidade HTTP para saúde, métricas, configuração e status da pipeline - Utilitários de configuração compartilhada e acesso ao banco de dados - Utilitários de monitoramento e componentes principais da pipeline que fornecem estado de tempo de execução - Persistência baseada em cache para instantâneos de status usados por dashboards
graph TB
subgraph "Camada de Serviço"
A["Aplicativo FastAPI<br/>apps/service/app.py"]
B["Rotas de Status<br/>apps/service/routes/status.py"]
C["Módulo de Configuração<br/>apps/shared/config.py"]
D["Acesso ao Banco de Dados<br/>apps/shared/db.py"]
E["Monitor de Watchdog<br/>apps/service/monitor/watchdog.py"]
end
subgraph "Pipeline Principal"
F["Núcleo da Pipeline<br/>apps/service/core/pipeline.py"]
G["Núcleo da Varredura<br/>apps/service/core/scan.py"]
end
subgraph "Estado de Tempo de Execução"
H["Cache de Status<br/>cache/status.json"]
end
A --> B
B --> C
B --> D
B --> E
B --> F
B --> G
B --> H
Fontes do Diagrama - app.py - status.py - config.py - db.py - watchdog.py - pipeline.py - scan.py - status.json
Fontes da Seção - app.py - status.py - config.py - db.py - watchdog.py - pipeline.py - scan.py - status.json
Componentes Principais¶
- Pontos de Extremidade de Verificação de Saúde: Fornece sinais de vivacidade/prontidão, verificações de conectividade com o banco de dados e disponibilidade geral do serviço.
- Coleta de Métricas: Expor indicadores de CPU, memória, disco e profundidade da fila.
- Monitoramento da Pipeline: Exibir progresso da varredura, taxas de processamento e dicas de gargalos.
- Resumo da Configuração: Retornar um instantâneo sanitizado da configuração atual e informações de versão.
- Atualizações em Tempo Real: Oferecer fluxos WebSocket para status e eventos ao vivo.
Esses componentes são conectados ao aplicativo FastAPI e dependem de módulos de configuração e banco de dados compartilhados. Os módulos de monitor de watchdog e núcleo da pipeline fornecem estado de tempo de execução.
Fontes da Seção - status.py - app.py - config.py - db.py - watchdog.py - pipeline.py - scan.py
Visão Geral da Arquitetura¶
A pilha de monitoramento integra pontos de extremidade HTTP com provedores de estado internos e canais em tempo real opcionais.
sequenceDiagram
participant Cliente as "Cliente"
participant Aplicativo as "Aplicativo FastAPI"
participant Rotas as "Rotas de Status"
participant Configuração as "Configuração"
participant BancoDeDados as "Banco de Dados"
participant Watchdog as "Monitor de Watchdog"
participant Pipeline as "Núcleo da Pipeline"
participant Cache as "Cache de Status"
Cliente->>Aplicativo : GET /saúde
Aplicativo->>Rotas : handle_saúde()
Rotas->>Configuração : ler_configuração()
Rotas->>BancoDeDados : testar_conexão()
Rotas->>Watchdog : obter_métricas_do_sistema()
Rotas->>Pipeline : obter_status_da_pipeline()
Rotas->>Cache : ler_instantâneo_de_status()
Rotas-->>Cliente : {status, verificações, métricas}
Cliente->>Aplicativo : GET /métricas
Aplicativo->>Rotas : handle_métricas()
Rotas->>Watchdog : coletar_cpu_memória_disco()
Rotas->>Pipeline : coletar_profundidade_da_fila_taxas()
Rotas-->>Cliente : {cpu, memória, disco, fila, taxas}
Cliente->>Aplicativo : WS /ws/status
Aplicativo->>Rotas : abrir_websocket()
Rotas->>Watchdog : assinar_atualizações()
Rotas->>Pipeline : transmitir_eventos()
Rotas-->>Cliente : Quadros SSE/WebSocket
Fontes do Diagrama - status.py - app.py - config.py - db.py - watchdog.py - pipeline.py - status.json
Análise Detalhada dos Componentes¶
Pontos de Extremidade de Verificação de Saúde¶
Propósito: - Vida: Confirme se o processo está vivo e respondendo. - Prontidão: Valide dependências (banco de dados, serviços externos). - Disponibilidade do Serviço: Agregue a saúde dos componentes em um único status.
Comportamentos-chave: - Retorna um status geral derivado de verificações individuais. - Inclui detalhes por verificação, como nome do componente, status e mensagens de erro quando aplicável. - Suporta tempos de resposta rápidos adequados para sondas e balanceadores de carga.
Campos típicos: - Status geral - Carimbo de data e hora - Verificações: lista de status dos componentes - Diagnósticos ou metadados de versão opcionais
Orientação operacional: - Use vida para reiniciar a orquestração de contêineres. - Use prontidão para controlar o tráfego até que as dependências estejam prontas.
Fontes da Seção - status.py - app.py - db.py
Coleta de Métricas do Sistema¶
Propósito: - Forneça métricas operacionais para CPU, memória, disco e profundidade da fila. - Permita alertas e planejamento de capacidade.
Métricas típicas incluem: - Uso de CPU em porcentagem - Uso de memória e memória disponível - Uso de disco e espaço livre - Profundidade da fila e taxas de processamento
Fontes de dados: - Métricas de nível de sistema por meio do monitor de watchdog - Internos da pipeline para profundidade da fila e taxa de processamento - Instantâneos com cache opcionais para visualizações históricas
Considerações de resposta: - Mantenha respostas leves e rápidas. - Evite I/O de bloqueio; prefira leituras não bloqueadoras.
Fontes da Seção - status.py - watchdog.py - pipeline.py
Pontos de Monitoramento da Pipeline¶
Propósito: - Mostre o progresso da varredura, taxas de processamento e identifique gargalos.
Capacidades-chave: - Fase atual da varredura e porcentagem de conclusão - Contadores de taxa de processamento (itens processados por janela de tempo) - Indicadores de gargalo (por exemplo, estágios lentos, pressão de retorno) - Tendências históricas por meio de instantâneos com cache
Pontos de integração: - Lê do núcleo da pipeline para estados de estágio - Agrega profundidades da fila e durações de processamento - Persiste instantâneos no cache para dashboards opcionais
Fontes da Seção - status.py - pipeline.py - scan.py - status.json
Resumo da Configuração, Versão e Dependências¶
Propósito: - Forneça uma visão segura e sanitizada da configuração atual. - Inclua a versão do aplicativo e o status de dependência quando relevante.
Comportamento: - Exclui valores sensíveis (por exemplo, segredos, tokens). - Resume configurações principais que afetam o monitoramento e o comportamento da pipeline. - Relata a versão e, opcionalmente, a saúde da dependência.
Casos de uso: - Auditoria de configuração implantada - Depuração de diferenças de ambiente - Validação de flags de recurso e limites
Fontes da Seção - status.py - config.py
Atualizações em Tempo Real por meio de WebSocket¶
Propósito: - Transmitir status e eventos ao vivo para dashboards e clientes de alerta.
Recursos: - Conexão persistente para atualizações contínuas - Notificações baseadas em eventos para marcos da pipeline e erros - Tratamento de pressão de retorno para evitar sobrecarregar os clientes
Notas de implementação: - Manipuladores de rotas gerenciam o ciclo de vida da conexão - Watchdog e pipeline emitem eventos consumidos pelo manipulador WebSocket - Clientes podem se inscrever em tipos de eventos específicos ou filtros
Fontes da Seção - status.py - watchdog.py - pipeline.py
Fluxos de Trabalho de Exemplo¶
Automação de Verificação de Saúde¶
- GET HTTP periódico para o ponto de extremidade de saúde.
- Analise o status geral e os resultados das verificações.
- Dispare alertas se a prontidão falhar ou verificações críticas relatam erros.
Integração de Alerta¶
- Assine eventos WebSocket para falhas críticas.
- Correlacione com picos de métricas (CPU, memória, profundidade da fila).
- Escale com base em limites e duração.
Configuração de Monitoramento de Desempenho¶
- Polle o ponto de extremidade de métricas em intervalos regulares.
- Armazene dados de série temporal em um backend de métricas.
- Construa dashboards para CPU, memória, disco, profundidade da fila e taxa de processamento.
[Nenhuma fonte necessária, pois esta seção fornece orientação geral]
Análise de Dependências¶
Os pontos de extremidade de monitoramento dependem de: - Módulo de configuração para configurações - Módulo de banco de dados para verificações de conectividade - Monitor de watchdog para métricas do sistema - Núcleo da pipeline para estado de processamento - Cache para instantâneos persistidos
graph LR
Rotas["Rotas de Status"] --> Configuração["Configuração"]
Rotas --> BancoDeDados["Acesso ao Banco de Dados"]
Rotas --> Watchdog["Monitor de Watchdog"]
Rotas --> Pipeline["Núcleo da Pipeline"]
Rotas --> Cache["Cache de Status"]
Fontes do Diagrama - status.py - config.py - db.py - watchdog.py - pipeline.py - status.json
Fontes da Seção - status.py - config.py - db.py - watchdog.py - pipeline.py - status.json
Considerações de Desempenho¶
- Mantenha as verificações de saúde leves e idempotentes.
- Evite I/O pesado nas verificações de prontidão; use timeouts e lógica de atalho.
- Debounce a coleta de métricas para evitar sobrecarga durante períodos de alta carga.
- Use cache para agregações caras e sirva instantâneos do cache quando apropriado.
- Implemente limitação de taxa em assinaturas WebSocket para proteger recursos do servidor.
[Nenhuma fonte necessária, pois esta seção fornece orientação geral]
Guia de Solução de Problemas¶
Problemas comuns e resoluções: - Falhas de verificação de saúde: Inspecte diagnósticos e mensagens de erro por verificação. Verifique credenciais do banco de dados e alcançabilidade da rede. - Métricas desatualizadas: Certifique-se de que o watchdog esteja em execução e tenha permissões para ler estatísticas do sistema. - Paradas da pipeline: Revise a profundidade da fila e as taxas de processamento; procure indicadores de gargalo no status da pipeline. - Desconexões WebSocket: Verifique a lógica de reconexão do lado do cliente e os limites de assinatura do lado do servidor.
Fontes da Seção - status.py - watchdog.py - pipeline.py
Conclusão¶
As APIs de monitoramento e saúde de Nexo fornecem visibilidade essencial para a saúde do aplicativo, recursos do sistema e desempenho da pipeline. Combinando pontos de extremidade HTTP com transmissão em tempo real, equipes podem construir automação robusta, alertas e dashboards. Seguir as práticas recomendadas garante operação confiável e observabilidade escalável.
[Nenhuma fonte necessária, pois esta seção resume sem analisar arquivos específicos]
Apêndices¶
Resumo de Referência de Pontos de Extremidade¶
- Verificação de Saúde: Status do aplicativo, conectividade com o banco de dados, disponibilidade do serviço
- Métricas: CPU, memória, disco, profundidade da fila, taxas de processamento
- Monitoramento da Pipeline: Progresso da varredura, taxa de processamento, dicas de gargalo
- Resumo da Configuração: Configuração sanitizada, informações de versão, status de dependência
- Atualizações em Tempo Real: WebSocket para status e eventos ao vivo
[Nenhuma fonte necessária, pois esta seção fornece orientação geral]