Ir para o conteúdo

Histórico & API de Logging

Arquivos Referenciados Neste Documento - apps/service/routes/logs.py - apps/service/routes/history.py - apps/shared/models/action_log.py - src/database/logs_db.py - src/logger.py - apps/dashboard/src/pages/Logs.tsx - apps/dashboard-v1-backup/src/services/sse.js

Tabela de Conteúdo

  1. Introdução
  2. Estrutura do Projeto
  3. Componentes Principais
  4. Visão Geral da Arquitetura
  5. Análise Detalhada dos Componentes
  6. Análise de Dependências
  7. Considerações de Desempenho
  8. Guia de Solução de Problemas
  9. Conclusão
  10. Apêndices

Introdução

Este documento fornece documentação abrangente da API para o sistema de histórico e logging do Nexo. Ele aborda pontos de extremidade para recuperar logs de ações, eventos do sistema e trilhas de auditoria; capacidades de filtragem e busca; gerenciamento de nível de log; políticas de rotação; back-ends de armazenamento; funcionalidade de exportação; streaming em tempo real via Server-Sent Events (SSE); consultas de análise; integrações de monitoramento de desempenho; configuração de alertas; estratégias de retenção e arquivamento; e considerações de conformidade para logging de auditoria.

O sistema é implementado como um serviço FastAPI com persistência baseada em banco de dados e um stream SSE opcional para monitoramento em tempo real. O frontend inclui uma página de Logs que consome essas APIs e streams.

Estrutura do Projeto

O subsistema de logging e histórico abrange rotas de backend, modelos de dados, acesso ao banco de dados, configuração do logger e a interface do usuário do dashboard:

  • Rotas de backend expõem pontos de extremidade REST para logs e histórico, além de streaming SSE.
  • Modelos de dados definem a estrutura dos logs de ações e entidades relacionadas.
  • Camada de banco de dados implementa construtores de consultas e ajudantes de paginação.
  • Módulo do logger configura níveis, manipuladores e rotação.
  • Páginas do dashboard consomem as APIs e renderizam logs e streams.
graph TB
subgraph "Serviço"
RLOG["routes/logs.py"]
RHIST["routes/history.py"]
LDB["database/logs_db.py"]
LCFG["logger.py"]
end
subgraph "Modelos"
MLOG["models/action_log.py"]
end
subgraph "Dashboard"
DLOG["pages/Logs.tsx"]
DSSE["services/sse.js"]
end
RLOG --> LDB
RHIST --> LDB
RLOG --> MLOG
RHIST --> MLOG
LCFG -.-> RLOG
DLOG --> RLOG
DLOG --> RHIST
DLOG --> DSSE

Fontes do Diagrama - apps/service/routes/logs.py - apps/service/routes/history.py - src/database/logs_db.py - apps/shared/models/action_log.py - src/logger.py - apps/dashboard/src/pages/Logs.tsx - apps/dashboard-v1-backup/src/services/sse.js

Fontes da Seção - apps/service/routes/logs.py - apps/service/routes/history.py - src/database/logs_db.py - apps/shared/models/action_log.py - src/logger.py - apps/dashboard/src/pages/Logs.tsx - apps/dashboard-v1-backup/src/services/sse.js

Componentes Principais

  • Modelo de Log de Ação: Define campos como carimbo de data/hora, tipo de evento, gravidade, tags, mensagem e identificadores de correlação usados em logs e histórico.
  • Rota de Logs: Fornece pontos de extremidade REST para listar, filtrar, buscar, paginar e exportar logs. Também expõe um ponto de extremidade SSE para streaming em tempo real.
  • Rota de Histórico: Exponde pontos de extremidade para ações e decisões históricas, incluindo consultas limitadas por tempo e resumos de agregação.
  • Camada de Banco de Dados: Implementa consultas eficientes, filtragem por múltiplos critérios, classificação e paginação sobre a tabela de logs.
  • Configuração do Logger: Centraliza o gerenciamento de nível de log, seleção de manipuladores e políticas de rotação.

Responsabilidades principais: - Filtragem e busca por carimbos de data/hora, tipos de eventos, níveis de gravidade e tags personalizadas. - Exportação de logs em vários formatos com compressão opcional. - Streaming de novas entradas de log via SSE para dashboards em tempo real. - Aplicação de políticas de retenção e rotação em camadas de aplicação e armazenamento.

Fontes da Seção - apps/shared/models/action_log.py - apps/service/routes/logs.py - apps/service/routes/history.py - src/database/logs_db.py - src/logger.py

Visão Geral da Arquitetura

A arquitetura de logging combina persistência estruturada, consultas flexíveis e entrega em tempo real:

sequenceDiagram
participant Cliente as "Cliente/Dashboard"
participant API as "Serviço FastAPI"
participant DB as "Camada de Banco de Dados"
participant Armazenamento as "Back-end de Armazenamento"
participant SSE as "Stream SSE"
Cliente->>API : "GET /api/logs?filtros..."
API->>DB : "construir_query(filtros)"
DB->>Armazenamento : "SELECT ... ORDER BY ts DESC LIMIT/PAGINAÇÃO"
Armazenamento-->>DB : "Linhas"
DB-->>API : "Resultados paginados"
API-->>Cliente : "Resposta JSON"
Cliente->>API : "GET /api/logs/stream"
API->>SSE : "Abrir stream"
Armazenamento-->>API : "Nova entrada de log"
API-->>Cliente : "evento : log\n dados : {...}"

Fontes do Diagrama - apps/service/routes/logs.py - src/database/logs_db.py

Análise Detalhada dos Componentes

API de Logs

Pontos de extremidade: - Listar e filtrar logs - Buscar logs - Paginar logs - Exportar logs - Streaming em tempo real (SSE)

Filtros comuns: - Intervalo de tempo: start_time, end_time - Tipo de evento: event_type - Nível de gravidade: severity - Tags: tag (repetível ou separada por vírgulas) - Busca de texto: q (subcadeia de mensagem) - ID de correlação: correlation_id - Origem/sistema: source - Paginação: page, page_size - Classificação: sort_by, sort_order

Opções de exportação: - Formato: json, csv, parquet (se habilitado) - Compressão: gzip, nenhuma - Escopo: subconjunto filtrado ou conjunto de dados completo (sujeito a limites)

SSE: - Ponto de extremidade: /api/logs/stream - Nome do evento: log - Payload: registro de log único - Reconexão: cliente lida com reconexões e last-event-id se suportado

Padrões de uso de exemplo: - Recuperar erros da última hora marcados com “scan”: - Parâmetros de consulta incluem severity=ERROR, start_time=now-1h, tag=scan - Exportar recentes avisos como CSV com compressão gzip: - Parâmetros incluem severity=WARNING, format=csv, compression=gzip

Notas: - Exportações grandes devem usar paginação ou IDs de trabalho do lado do servidor para evitar solicitações bloqueadas. - A correspondência de tags suporta correspondência exata e contém semântica dependendo da implementação.

Fontes da Seção - apps/service/routes/logs.py - src/database/logs_db.py

API de Histórico

Pontos de extremidade: - Listar ações históricas - Obter detalhes por ID - Contagens agregadas por intervalos de tempo - Filtrar por intervalos de data, tipos de eventos e tags

Casos de uso: - Recuperação de trilhas de auditoria para conformidade - Análise de tendências ao longo do tempo - Linhagem e proveniência de decisões

Filtragem e classificação: - Janelas de tempo, tipos de eventos, tags - Classificar por carimbo de data/hora em ordem decrescente por padrão - Pontos de extremidade de agrupamento/agregação opcionais

Fontes da Seção - apps/service/routes/history.py - src/database/logs_db.py

Modelo de Dados: Log de Ação

Campos típicos incluem: - id: identificador único - carimbo de data/hora: ISO 8601 UTC - tipo de evento: categoria de evento - gravidade: INFO, WARNING, ERROR, CRITICAL - tags: pares de chave-valor ou matriz - mensagem: texto legível por humanos - id de correlação: rastreamento de solicitação ou operação - origem: componente ou subsistema - metadados: contexto estruturado adicional

Complexidade: - Índices em carimbo de data/hora, tipo de evento, gravidade, tags e id de correlação melhoram o desempenho da consulta. - Consultas de tags podem aproveitar índices JSON ou tabelas normalizadas dependendo do back-end de armazenamento.

Fontes da Seção - apps/shared/models/action_log.py

Camada de Banco de Dados

Responsabilidades: - Construir consultas parametrizadas a partir de filtros - Aplicar paginação e classificação - Otimizar consultas comuns com índices - Suportar consultas de exportação com streaming quando possível

Otimizações: - Use índices parciais para filtros de alta cardinalidade como gravidade e tipo de evento. - Materialize agregações para consultas de análise frequentes. - Transfira conjuntos de resultados grandes para reduzir a pressão de memória.

Fontes da Seção - src/database/logs_db.py

Configuração do Logger

Recursos: - Gerenciamento de nível de log global - Múltiplos manipuladores (console, arquivo, remoto) - Políticas de rotação (baseadas em tamanho, baseadas em tempo) - Logging estruturado com esquema consistente

Políticas: - Tamanho máximo de arquivo e contagem de backup - Período de retenção antes do arquivamento/exclusão - Compressão de arquivos rotacionados

Pontos de integração: - Inicialização do aplicativo inicializa o logger - Rotas e serviços emitem logs estruturados - Stream SSE lê de um buffer compartilhado ou tailer

Fontes da Seção - src/logger.py

Integração do Dashboard

Componentes do frontend: - Página de Logs exibe logs paginados e filtros - Consumidor SSE se inscreve em atualizações em tempo real - Controles de exportação acionam trabalhos de download

Notas de implementação: - Reduzir as alterações de filtro para evitar solicitações excessivas - Lidar com reconexão e retrocesso SSE - Renderizar gravidade e tags com emblemas para varredura rápida

Fontes da Seção - apps/dashboard/src/pages/Logs.tsx - apps/dashboard-v1-backup/src/services/sse.js

Análise de Dependências

Dependências de alto nível entre componentes:

graph LR
RLOG["routes/logs.py"] --> LDB["database/logs_db.py"]
RHIST["routes/history.py"] --> LDB
RLOG --> MLOG["models/action_log.py"]
RHIST --> MLOG
LCFG["logger.py"] --> RLOG
DLOG["pages/Logs.tsx"] --> RLOG
DLOG --> RHIST
DSSE["services/sse.js"] --> RLOG

Fontes do Diagrama - apps/service/routes/logs.py - apps/service/routes/history.py - src/database/logs_db.py - apps/shared/models/action_log.py - src/logger.py - apps/dashboard/src/pages/Logs.tsx - apps/dashboard-v1-backup/src/services/sse.js

Fontes da Seção - apps/service/routes/logs.py - apps/service/routes/history.py - src/database/logs_db.py - apps/shared/models/action_log.py - src/logger.py - apps/dashboard/src/pages/Logs.tsx - apps/dashboard-v1-backup/src/services/sse.js

Considerações de Desempenho

  • Estratégia de indexação: Certifique-se de que existam índices em carimbo de data/hora, tipo de evento, gravidade, tags e id de correlação.
  • Padrões de paginação: Impor tamanhos de página razoáveis e limites máximos para evitar consultas pesadas.
  • Streaming de exportação: Para conjuntos de dados grandes, prefira streaming do lado do servidor ou trabalhos em segundo plano com sondagem.
  • Escalabilidade do SSE: Use um canal de publicação-assinatura ou fila para distribuir eventos para muitos clientes de forma eficiente.
  • Agregações: Pré-computar métricas de séries temporais para dashboards para reduzir a carga na tabela de logs principal.
  • Cache: Cache combinações de filtro frequentes com TTLs curtos quando apropriado.

[Nenhuma fonte necessária, pois esta seção fornece orientação geral]

Guia de Solução de Problemas

Problemas comuns e resoluções: - Índices ausentes causando consultas lentas: Adicione índices compostos para combinações de filtro comuns. - Desconexões SSE: Implemente retrocesso exponencial e tratamento de last-event-id no cliente. - Tempos limite de exportação: Alterne para trabalhos de exportação assíncronos e forneça pontos de extremidade de status. - Tags de alta cardinalidade: Normalize tags em uma tabela separada ou use JSONB com índices GIN. - Conflitos de rotação de log: Certifique-se de bloqueios de arquivo exclusivos e reinicializações graciosas durante a rotação.

Verificações operacionais: - Verifique se as configurações de nível de log estão corretas para ambientes. - Confirme se as políticas de rotação estão alinhadas com a capacidade de disco e os requisitos de retenção. - Valide a disponibilidade do ponto de extremidade SSE e a limitação de taxa.

Fontes da Seção - src/logger.py - apps/service/routes/logs.py

Conclusão

O sistema de histórico e logging do Nexo oferece APIs REST robustas para consultar e exportar logs, streaming em tempo real via SSE e comportamento de logging configurável. Com indexação adequada, estratégias de paginação e exportação, ele atende às necessidades de monitoramento operacional e conformidade. O dashboard se integra perfeitamente para visualizar logs e eventos em tempo real.

[Nenhuma fonte necessária, pois esta seção resume sem analisar arquivos específicos]

Apêndices

Resumo da Referência da API

  • GET /api/logs
  • Propósito: Listar e filtrar logs
  • Filtros: start_time, end_time, event_type, severity, tag, q, correlation_id, source, page, page_size, sort_by, sort_order
  • Resposta: Lista paginada de registros de log
  • GET /api/logs/export
  • Propósito: Exportar logs
  • Parâmetros: format=json|csv|parquet, compression=gzip|none, scope=filtered|full, limit
  • Resposta: Link de download ou fluxo de arquivo
  • GET /api/logs/stream
  • Propósito: Stream SSE de novos logs
  • Evento: log
  • Payload: Registro de log único
  • GET /api/history/actions
  • Propósito: Listar ações históricas
  • Filtros: intervalo de tempo, tipo de evento, tags
  • Resposta: Lista paginada
  • GET /api/history/actions/{id}
  • Propósito: Obter detalhes da ação
  • Resposta: Registro da ação
  • GET /api/history/aggregates
  • Propósito: Contagens agregadas em intervalos de tempo
  • Parâmetros: bucket=hour|day|week, group_by=event_type|severity
  • Resposta: Série de contagens agregadas

[Nenhuma fonte necessária, pois esta seção fornece orientação geral]

Consultas de Exemplo

  • Erros na última hora com tag “scan”:
  • severity=ERROR, start_time=now-1h, tag=scan
  • Avisos exportados como CSV com compressão gzip:
  • severity=WARNING, format=csv, compression=gzip
  • Monitoramento em tempo real:
  • Conectar-se a /api/logs/stream e se inscrever no evento “log”

[Nenhuma fonte necessária, pois esta seção fornece orientação geral]

Gerenciamento de Nível de Log

  • Nível global: Definido via configuração no início
  • Níveis específicos de manipulador: Console vs manipuladores de arquivo podem diferir
  • Atualizações dinâmicas: Recarregar configuração sem reinicializar se suportado

Fontes da Seção - src/logger.py

Políticas de Rotação de Log

  • Rotação baseada em tamanho: Rotacionar quando o arquivo exceder o limite
  • Rotação baseada em tempo: Rotacionar diariamente/horariamente
  • Retenção: Manter N backups ou excluir após dias
  • Compressão: Comprimir arquivos rotacionados para economizar espaço

Fontes da Seção - src/logger.py

Back-ends de Armazenamento

  • Banco de dados relacional: Armazenamento principal para logs e histórico
  • Armazenamento de objetos: Arquivamento de logs antigos e exportações
  • Sistema de arquivos: Rotação local e estágio temporário

[Nenhuma fonte necessária, pois esta seção fornece orientação geral]

Capacidades de Busca

  • Consultas de intervalo de carimbo de data/hora
  • Correspondência exata e contém para tipo de evento e mensagem
  • Filtros de tag com semântica AND/OR
  • Rastreamento de ID de correlação entre subsistemas

Fontes da Seção - src/database/logs_db.py

Streaming em Tempo Real (SSE)

  • Ciclo de vida da conexão: Abrir, receber eventos, lidar com desconexões
  • Reconexão do cliente: Retentativa com retrocesso
  • Limitação de taxa: Limitar por cliente para proteger o servidor

Fontes da Seção - apps/service/routes/logs.py - apps/dashboard-v1-backup/src/services/sse.js

Funcionalidade de Exportação de Log

  • Formatos: JSON, CSV, Parquet (opcional)
  • Compressão: Gzip para downloads
  • Exportação baseada em trabalho: Para conjuntos de dados grandes, retornar ID de trabalho e status

Fontes da Seção - apps/service/routes/logs.py

Consultas de Análise de Log

  • Principais fontes de erro por hora
  • Distribuição de gravidades ao longo do tempo
  • Frequência de tags e tendências
  • Tempo médio entre eventos críticos

[Nenhuma fonte necessária, pois esta seção fornece orientação geral]

Integrações de Monitoramento de Desempenho

  • Métricas: Taxa de ingestão de log, latência de consulta, conexões SSE
  • Rastreamento: Propagar ID de correlação por meio dos serviços
  • Alertas: Limites em taxas de erro e atraso

[Nenhuma fonte necessária, pois esta seção fornece orientação geral]

Configuração do Sistema de Alertas

  • Exemplos de regras: Taxa de erro > X por minuto, nenhum log por Y minutos
  • Canais: Webhook, e-mail, plataformas de mensagens
  • Supressão: Deduplicar alertas e cooldowns

[Nenhuma fonte necessária, pois esta seção fornece orientação geral]

Estratégias de Retenção e Arquivamento

  • Armazenamento quente: Logs recentes com consultas rápidas
  • Armazenamento morno: Logs mais antigos com acesso mais lento
  • Arquivo frio: Retenção de longo prazo com compressão
  • Políticas de ciclo de vida automatizadas com base em idade e tamanho

[Nenhuma fonte necessária, pois esta seção fornece orientação geral]

Requisitos de Conformidade para Logging de Auditoria

  • Imutabilidade: Logs apenas de acréscimo com checksums
  • Integridade: Cadeias de hash ou assinaturas para entradas críticas
  • Controle de acesso: Acesso baseado em papel para logs sensíveis
  • Trilhas de auditoria: Registrar quem acessou ou modificou configurações
  • Minimização de dados: Redação de informações de identificação pessoal quando necessário

[Nenhuma fonte necessária, pois esta seção fornece orientação geral]