Skip to main content

Retenção e Arquivamento de Logs

Visão Geral

O módulo de retenção e arquivamento de logs do RiskFlow gerencia o ciclo de vida dos dados de auditoria e logs do sistema, garantindo conformidade com políticas de retenção, otimizando o uso de armazenamento e mantendo a performance do sistema. Este módulo permite configurar períodos de retenção, arquivar logs antigos e gerenciar o acesso a dados históricos.

Endpoints

1. Obter Configuração de Retenção

Retorna a configuração atual de retenção de logs do sistema.

GET /api/retencao-logs/configuracao

Exemplo de Requisição (cURL)

curl -X GET \
'http://localhost:3000/api/retencao-logs/configuracao' \
-H 'x-api-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Exemplo de Requisição (JavaScript - Fetch API)

const token = localStorage.getItem('token');

fetch('http://localhost:3000/api/retencao-logs/configuracao', {
method: 'GET',
headers: {
'x-api-key': token
}
})
.then(response => response.json())
.then(data => console.log('Configuração de retenção:', data))
.catch(error => console.error('Erro ao buscar configuração de retenção:', error));

Exemplo de Requisição (Node.js - Axios)

const axios = require('axios');
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';

axios.get('http://localhost:3000/api/retencao-logs/configuracao', {
headers: {
'x-api-key': token
}
})
.then(response => {
console.log('Configuração de retenção:', response.data);
})
.catch(error => console.error('Erro ao buscar configuração de retenção:', error));

Resposta de Sucesso (200 OK)

{
"politicas": [
{
"tipo": "auditoria",
"nivel": "info",
"periodo_retencao_ativo": 90,
"periodo_retencao_arquivo": 365,
"periodo_retencao_total": 455,
"compressao": true,
"anonimizacao": false
},
{
"tipo": "auditoria",
"nivel": "alerta",
"periodo_retencao_ativo": 180,
"periodo_retencao_arquivo": 730,
"periodo_retencao_total": 910,
"compressao": true,
"anonimizacao": false
},
{
"tipo": "auditoria",
"nivel": "erro",
"periodo_retencao_ativo": 365,
"periodo_retencao_arquivo": 1095,
"periodo_retencao_total": 1460,
"compressao": true,
"anonimizacao": false
},
{
"tipo": "auditoria",
"nivel": "critico",
"periodo_retencao_ativo": 730,
"periodo_retencao_arquivo": 1825,
"periodo_retencao_total": 2555,
"compressao": true,
"anonimizacao": false
},
{
"tipo": "sistema",
"nivel": "info",
"periodo_retencao_ativo": 30,
"periodo_retencao_arquivo": 90,
"periodo_retencao_total": 120,
"compressao": true,
"anonimizacao": false
},
{
"tipo": "sistema",
"nivel": "erro",
"periodo_retencao_ativo": 90,
"periodo_retencao_arquivo": 275,
"periodo_retencao_total": 365,
"compressao": true,
"anonimizacao": false
}
],
"configuracao_geral": {
"frequencia_arquivamento": "0 0 * * 0",
"frequencia_limpeza": "0 2 * * 0",
"diretorio_arquivos": "/data/logs/arquivados",
"formato_arquivo": "parquet",
"compressao_padrao": "gzip",
"ultima_execucao_arquivamento": "2025-05-26T02:00:00Z",
"proxima_execucao_arquivamento": "2025-06-02T02:00:00Z"
}
}

2. Atualizar Configuração de Retenção

Atualiza a configuração de retenção de logs do sistema (requer permissão de administrador).

PUT /api/retencao-logs/configuracao

Corpo da Requisição

{
"politicas": [
{
"tipo": "auditoria",
"nivel": "info",
"periodo_retencao_ativo": 60,
"periodo_retencao_arquivo": 305,
"compressao": true,
"anonimizacao": false
},
{
"tipo": "auditoria",
"nivel": "alerta",
"periodo_retencao_ativo": 180,
"periodo_retencao_arquivo": 730,
"compressao": true,
"anonimizacao": false
}
],
"configuracao_geral": {
"frequencia_arquivamento": "0 0 * * 0",
"frequencia_limpeza": "0 2 * * 0",
"diretorio_arquivos": "/data/logs/arquivados",
"formato_arquivo": "parquet",
"compressao_padrao": "gzip"
}
}

Exemplo de Requisição (cURL)

curl -X PUT \
'http://localhost:3000/api/retencao-logs/configuracao' \
-H 'Content-Type: application/json' \
-H 'x-api-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
-d '{
"politicas": [
{
"tipo": "auditoria",
"nivel": "info",
"periodo_retencao_ativo": 60,
"periodo_retencao_arquivo": 305,
"compressao": true,
"anonimizacao": false
},
{
"tipo": "auditoria",
"nivel": "alerta",
"periodo_retencao_ativo": 180,
"periodo_retencao_arquivo": 730,
"compressao": true,
"anonimizacao": false
}
],
"configuracao_geral": {
"frequencia_arquivamento": "0 0 * * 0",
"frequencia_limpeza": "0 2 * * 0",
"diretorio_arquivos": "/data/logs/arquivados",
"formato_arquivo": "parquet",
"compressao_padrao": "gzip"
}
}'

Exemplo de Requisição (Node.js - Axios)

const axios = require('axios');
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';

const configuracao = {
politicas: [
{
tipo: "auditoria",
nivel: "info",
periodo_retencao_ativo: 60,
periodo_retencao_arquivo: 305,
compressao: true,
anonimizacao: false
},
{
tipo: "auditoria",
nivel: "alerta",
periodo_retencao_ativo: 180,
periodo_retencao_arquivo: 730,
compressao: true,
anonimizacao: false
}
],
configuracao_geral: {
frequencia_arquivamento: "0 0 * * 0",
frequencia_limpeza: "0 2 * * 0",
diretorio_arquivos: "/data/logs/arquivados",
formato_arquivo: "parquet",
compressao_padrao: "gzip"
}
};

axios.put('http://localhost:3000/api/retencao-logs/configuracao', configuracao, {
headers: {
'Content-Type': 'application/json',
'x-api-key': token
}
})
.then(response => {
console.log('Configuração atualizada:', response.data);
})
.catch(error => console.error('Erro ao atualizar configuração:', error));

Resposta de Sucesso (200 OK)

{
"mensagem": "Configuração de retenção atualizada com sucesso",
"politicas_atualizadas": 2,
"configuracao_geral_atualizada": true,
"ultima_atualizacao": "2025-06-03T19:30:00Z"
}

3. Executar Arquivamento Manual

Inicia manualmente o processo de arquivamento de logs antigos (requer permissão de administrador).

POST /api/retencao-logs/arquivar

Parâmetros de Consulta

ParâmetroTipoObrigatórioDescrição
tipostringNãoTipo de log para arquivar (ex: "auditoria", "sistema")
data_limitestring (date-time)NãoData limite para arquivamento (logs anteriores a esta data serão arquivados)
nivelstringNãoNível específico para arquivar (ex: "info", "alerta", "erro", "critico")

Exemplo de Requisição (cURL)

curl -X POST \
'http://localhost:3000/api/retencao-logs/arquivar?tipo=auditoria&data_limite=2025-05-01T00:00:00Z' \
-H 'x-api-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Exemplo de Requisição (JavaScript - Fetch API)

const token = localStorage.getItem('token');

const params = new URLSearchParams({
tipo: 'auditoria',
data_limite: '2025-05-01T00:00:00Z'
});

fetch(`http://localhost:3000/api/retencao-logs/arquivar?${params.toString()}`, {
method: 'POST',
headers: {
'x-api-key': token
}
})
.then(response => response.json())
.then(data => console.log('Resultado do arquivamento:', data))
.catch(error => console.error('Erro ao executar arquivamento:', error));

Resposta de Sucesso (202 Accepted)

{
"mensagem": "Processo de arquivamento iniciado",
"job_id": "550e8400-e29b-41d4-a716-446655440500",
"parametros": {
"tipo": "auditoria",
"data_limite": "2025-05-01T00:00:00Z",
"nivel": null
},
"status": "em_andamento",
"inicio": "2025-06-03T19:45:00Z",
"estimativa_conclusao": "2025-06-03T19:50:00Z"
}

4. Verificar Status de Arquivamento

Verifica o status de um processo de arquivamento em andamento ou concluído.

GET /api/retencao-logs/arquivamento/:jobId/status

Parâmetros de URL

ParâmetroTipoObrigatórioDescrição
jobIduuidSimID do job de arquivamento

Exemplo de Requisição (cURL)

curl -X GET \
'http://localhost:3000/api/retencao-logs/arquivamento/550e8400-e29b-41d4-a716-446655440500/status' \
-H 'x-api-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Exemplo de Requisição (Node.js - Axios)

const axios = require('axios');
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';
const jobId = '550e8400-e29b-41d4-a716-446655440500';

axios.get(`http://localhost:3000/api/retencao-logs/arquivamento/${jobId}/status`, {
headers: {
'x-api-key': token
}
})
.then(response => {
console.log('Status do arquivamento:', response.data);
})
.catch(error => console.error('Erro ao verificar status do arquivamento:', error));

Resposta de Sucesso (200 OK - Em Andamento)

{
"job_id": "550e8400-e29b-41d4-a716-446655440500",
"status": "em_andamento",
"progresso": 45,
"inicio": "2025-06-03T19:45:00Z",
"estimativa_conclusao": "2025-06-03T19:50:00Z",
"registros_processados": 45000,
"registros_total": 100000,
"detalhes": {
"tipo": "auditoria",
"data_limite": "2025-05-01T00:00:00Z",
"nivel": null
}
}

Resposta de Sucesso (200 OK - Concluído)

{
"job_id": "550e8400-e29b-41d4-a716-446655440500",
"status": "concluido",
"progresso": 100,
"inicio": "2025-06-03T19:45:00Z",
"conclusao": "2025-06-03T19:49:30Z",
"duracao_segundos": 270,
"registros_processados": 100000,
"registros_arquivados": 98500,
"registros_ignorados": 1500,
"arquivos_gerados": [
"/data/logs/arquivados/auditoria_info_20250101_20250430.parquet.gz",
"/data/logs/arquivados/auditoria_alerta_20250101_20250430.parquet.gz",
"/data/logs/arquivados/auditoria_erro_20250101_20250430.parquet.gz"
],
"espaco_liberado": "45.8 MB",
"detalhes": {
"tipo": "auditoria",
"data_limite": "2025-05-01T00:00:00Z",
"nivel": null
}
}

5. Listar Arquivos de Logs Arquivados

Retorna uma lista de arquivos de logs arquivados disponíveis para consulta.

GET /api/retencao-logs/arquivos

Parâmetros de Consulta

ParâmetroTipoObrigatórioDescrição
tipostringNãoFiltrar por tipo de log (ex: "auditoria", "sistema")
nivelstringNãoFiltrar por nível (ex: "info", "alerta", "erro", "critico")
data_iniciostring (date-time)NãoFiltrar por data inicial do período arquivado
data_fimstring (date-time)NãoFiltrar por data final do período arquivado
pageintegerNãoNúmero da página (padrão: 1)
limitintegerNãoItens por página (padrão: 20, máx: 100)

Exemplo de Requisição (cURL)

curl -X GET \
'http://localhost:3000/api/retencao-logs/arquivos?tipo=auditoria&nivel=info' \
-H 'x-api-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Exemplo de Requisição (JavaScript - Fetch API)

const token = localStorage.getItem('token');

const params = new URLSearchParams({
tipo: 'auditoria',
nivel: 'info'
});

fetch(`http://localhost:3000/api/retencao-logs/arquivos?${params.toString()}`, {
method: 'GET',
headers: {
'x-api-key': token
}
})
.then(response => response.json())
.then(data => console.log('Arquivos de logs arquivados:', data))
.catch(error => console.error('Erro ao listar arquivos de logs arquivados:', error));

Resposta de Sucesso (200 OK)

{
"arquivos": [
{
"id": "550e8400-e29b-41d4-a716-446655440600",
"nome": "auditoria_info_20250101_20250331.parquet.gz",
"caminho": "/data/logs/arquivados/auditoria_info_20250101_20250331.parquet.gz",
"tipo": "auditoria",
"nivel": "info",
"periodo": {
"inicio": "2025-01-01T00:00:00Z",
"fim": "2025-03-31T23:59:59Z"
},
"tamanho": "28.5 MB",
"registros": 65000,
"formato": "parquet",
"compressao": "gzip",
"data_arquivamento": "2025-04-07T02:00:00Z",
"data_expiracao": "2025-12-31T23:59:59Z"
},
{
"id": "550e8400-e29b-41d4-a716-446655440601",
"nome": "auditoria_info_20250401_20250430.parquet.gz",
"caminho": "/data/logs/arquivados/auditoria_info_20250401_20250430.parquet.gz",
"tipo": "auditoria",
"nivel": "info",
"periodo": {
"inicio": "2025-04-01T00:00:00Z",
"fim": "2025-04-30T23:59:59Z"
},
"tamanho": "17.3 MB",
"registros": 33500,
"formato": "parquet",
"compressao": "gzip",
"data_arquivamento": "2025-06-03T19:49:30Z",
"data_expiracao": "2026-01-31T23:59:59Z"
}
],
"pagination": {
"total": 2,
"page": 1,
"limit": 20,
"pages": 1
},
"resumo": {
"total_arquivos": 2,
"total_registros": 98500,
"espaco_total": "45.8 MB"
}
}

6. Consultar Logs Arquivados

Consulta logs arquivados com base em filtros específicos.

POST /api/retencao-logs/consulta

Corpo da Requisição

{
"arquivo_id": "550e8400-e29b-41d4-a716-446655440600",
"filtros": {
"entidade": "analise",
"operacao": "atualizar",
"usuario_id": "550e8400-e29b-41d4-a716-446655440003",
"data_inicio": "2025-02-01T00:00:00Z",
"data_fim": "2025-02-28T23:59:59Z"
},
"colunas": ["timestamp", "usuario.nome", "entidade", "entidade_id", "operacao", "descricao"],
"ordenacao": {
"campo": "timestamp",
"direcao": "desc"
},
"limite": 100,
"offset": 0
}

Exemplo de Requisição (cURL)

curl -X POST \
'http://localhost:3000/api/retencao-logs/consulta' \
-H 'Content-Type: application/json' \
-H 'x-api-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
-d '{
"arquivo_id": "550e8400-e29b-41d4-a716-446655440600",
"filtros": {
"entidade": "analise",
"operacao": "atualizar",
"usuario_id": "550e8400-e29b-41d4-a716-446655440003",
"data_inicio": "2025-02-01T00:00:00Z",
"data_fim": "2025-02-28T23:59:59Z"
},
"colunas": ["timestamp", "usuario.nome", "entidade", "entidade_id", "operacao", "descricao"],
"ordenacao": {
"campo": "timestamp",
"direcao": "desc"
},
"limite": 100,
"offset": 0
}'

Exemplo de Requisição (Node.js - Axios)

const axios = require('axios');
const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';

const consulta = {
arquivo_id: "550e8400-e29b-41d4-a716-446655440600",
filtros: {
entidade: "analise",
operacao: "atualizar",
usuario_id: "550e8400-e29b-41d4-a716-446655440003",
data_inicio: "2025-02-01T00:00:00Z",
data_fim: "2025-02-28T23:59:59Z"
},
colunas: ["timestamp", "usuario.nome", "entidade", "entidade_id", "operacao", "descricao"],
ordenacao: {
campo: "timestamp",
direcao: "desc"
},
limite: 100,
offset: 0
};

axios.post('http://localhost:3000/api/retencao-logs/consulta', consulta, {
headers: {
'Content-Type': 'application/json',
'x-api-key': token
}
})
.then(response => {
console.log('Resultado da consulta:', response.data);
})
.catch(error => console.error('Erro ao consultar logs arquivados:', error));

Resposta de Sucesso (200 OK)

{
"registros": [
{
"timestamp": "2025-02-28T15:45:00Z",
"usuario.nome": "João Silva",
"entidade": "analise",
"entidade_id": "550e8400-e29b-41d4-a716-446655440000",
"operacao": "atualizar",
"descricao": "Atualização de status da análise"
},
{
"timestamp": "2025-02-25T10:30:00Z",
"usuario.nome": "João Silva",
"entidade": "analise",
"entidade_id": "550e8400-e29b-41d4-a716-446655440007",
"operacao": "atualizar",
"descricao": "Adição de parecer à análise"
},
// ... mais registros
],
"meta": {
"total": 45,
"limite": 100,
"offset": 0,
"arquivo": {
"id": "550e8400-e29b-41d4-a716-446655440600",
"nome": "auditoria_info_20250101_20250331.parquet.gz",
"periodo": {
"inicio": "2025-01-01T00:00:00Z",
"fim": "2025-03-31T23:59:59Z"
}
},
"filtros_aplicados": {
"entidade": "analise",
"operacao": "atualizar",
"usuario_id": "550e8400-e29b-41d4-a716-446655440003",
"data_inicio": "2025-02-01T00:00:00Z",
"data_fim": "2025-02-28T23:59:59Z"
}
}
}

7. Executar Limpeza Manual

Inicia manualmente o processo de limpeza de logs expirados (requer permissão de administrador).

POST /api/retencao-logs/limpar

Parâmetros de Consulta

ParâmetroTipoObrigatórioDescrição
tipostringNãoTipo de log para limpar (ex: "auditoria", "sistema")
nivelstringNãoNível específico para limpar (ex: "info", "alerta", "erro", "critico")
modostringNãoModo de limpeza: "arquivados" (apenas logs arquivados), "todos" (logs ativos e arquivados expirados)

Exemplo de Requisição (cURL)

curl -X POST \
'http://localhost:3000/api/retencao-logs/limpar?tipo=auditoria&nivel=info&modo=arquivados' \
-H 'x-api-key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Exemplo de Requisição (JavaScript - Fetch API)

const token = localStorage.getItem('token');

const params = new URLSearchParams({
tipo: 'auditoria',
nivel: 'info',
modo: 'arquivados'
});

fetch(`http://localhost:3000/api/retencao-logs/limpar?${params.toString()}`, {
method: 'POST',
headers: {
'x-api-key': token
}
})
.then(response => response.json())
.then(data => console.log('Resultado da limpeza:', data))
.catch(error => console.error('Erro ao executar limpeza:', error));

Resposta de Sucesso (202 Accepted)

{
"mensagem": "Processo de limpeza iniciado",
"job_id": "550e8400-e29b-41d4-a716-446655440700",
"parametros": {
"tipo": "auditoria",
"nivel": "info",
"modo": "arquivados"
},
"status": "em_andamento",
"inicio": "2025-06-03T20:00:00Z",
"estimativa_conclusao": "2025-06-03T20:05:00Z"
}

Arquitetura de Retenção de Logs

O sistema implementa uma arquitetura de retenção de logs em três camadas:

1. Logs Ativos

  • Armazenados no banco de dados principal
  • Acesso rápido e consulta integrada com o restante do sistema
  • Período de retenção configurável por tipo e nível (geralmente 30-730 dias)

2. Logs Arquivados

  • Armazenados em arquivos otimizados (Parquet, com compressão)
  • Acesso mais lento, mas com capacidade de consulta
  • Período de retenção estendido (geralmente 90-1825 dias adicionais)
  • Organizados por tipo, nível e período

3. Logs Expirados

  • Removidos permanentemente do sistema
  • Opcionalmente, podem ser exportados antes da remoção para armazenamento externo de longo prazo

Processos Automáticos

O sistema executa automaticamente os seguintes processos:

1. Arquivamento

  • Executa conforme a frequência configurada (padrão: semanalmente)
  • Move logs ativos que ultrapassaram o período de retenção ativo para arquivos
  • Gera arquivos organizados por tipo, nível e período
  • Registra metadados sobre os arquivos gerados

2. Limpeza

  • Executa conforme a frequência configurada (padrão: semanalmente)
  • Remove logs arquivados que ultrapassaram o período de retenção total
  • Opcionalmente, pode exportar logs antes da remoção

Melhores Práticas

  1. Políticas de Retenção: Defina períodos de retenção adequados às necessidades de negócio e requisitos regulatórios.
  2. Níveis de Severidade: Use períodos de retenção mais longos para logs de maior severidade.
  3. Arquivamento Regular: Configure o arquivamento para executar regularmente, evitando acúmulo excessivo de logs ativos.
  4. Backup de Arquivos: Considere fazer backup dos arquivos de logs arquivados em armazenamento externo.
  5. Monitoramento de Espaço: Monitore o espaço utilizado pelos logs para evitar problemas de armazenamento.

Próximos Passos

Agora que você entende como utilizar o módulo de retenção e arquivamento de logs, pode explorar:

  • Auditoria - Para entender os tipos de logs gerados pelo sistema
  • Exportação - Para exportar logs antes de sua remoção
  • Métricas - Para monitorar o desempenho do sistema