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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tipo | string | Não | Tipo de log para arquivar (ex: "auditoria", "sistema") |
| data_limite | string (date-time) | Não | Data limite para arquivamento (logs anteriores a esta data serão arquivados) |
| nivel | string | Não | Ní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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| jobId | uuid | Sim | ID 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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tipo | string | Não | Filtrar por tipo de log (ex: "auditoria", "sistema") |
| nivel | string | Não | Filtrar por nível (ex: "info", "alerta", "erro", "critico") |
| data_inicio | string (date-time) | Não | Filtrar por data inicial do período arquivado |
| data_fim | string (date-time) | Não | Filtrar por data final do período arquivado |
| page | integer | Não | Número da página (padrão: 1) |
| limit | integer | Não | Itens 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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| tipo | string | Não | Tipo de log para limpar (ex: "auditoria", "sistema") |
| nivel | string | Não | Nível específico para limpar (ex: "info", "alerta", "erro", "critico") |
| modo | string | Não | Modo 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
- Políticas de Retenção: Defina períodos de retenção adequados às necessidades de negócio e requisitos regulatórios.
- Níveis de Severidade: Use períodos de retenção mais longos para logs de maior severidade.
- Arquivamento Regular: Configure o arquivamento para executar regularmente, evitando acúmulo excessivo de logs ativos.
- Backup de Arquivos: Considere fazer backup dos arquivos de logs arquivados em armazenamento externo.
- 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