Os logs de auditoria registram toda ação que altera o estado da sua organização — atribuição de funções, edições de engine, emissão de chaves de API, mudanças de cobrança — e exibem tudo em uma linha do tempo pesquisável e filtrável. Disponível no plano Enterprise, junto com Funções e permissões.
O log é append-only no nível do banco de dados: a conexão da aplicação não pode atualizar, excluir nem truncar linhas de auditoria. O que foi gravado, fica gravado.
O que é registrado#
Cada evento captura o ator, a ação, o alvo e o contexto HTTP em que a solicitação chegou.
| Campo | Observações |
|---|---|
| Ator | O usuário ou a chave de API que executou a ação |
| Ação | Um valor tipado, como engine.created ou member.role_changed |
| Alvo | A entidade afetada (por exemplo, uma engine, uma função ou um item do glossário) |
| Metadados | IDs de entidades relacionadas — nunca nomes, e-mails ou trechos de conteúdo |
| Contexto da solicitação | request_id, endereço IP, user agent — capturados quando a chamada chega por HTTP |
| Timestamp | UTC, além de um número de sequência monotônico para detectar lacunas |
Apenas IDs, por design
A coluna de metadados armazena IDs, não valores legíveis. A UI faz join com os nomes atuais no momento da leitura, então renomear uma engine ou um usuário não reescreve o histórico. Isso também evita conflitos entre as linhas de auditoria e o direito de apagamento da GDPR — não há conteúdo para redigir.
Ações cobertas#
Os eventos são agrupados em categorias que correspondem ao filtro do dashboard.
| Categoria | Ações disponíveis hoje |
|---|---|
| Organização | org.created, org.settings_updated, org.ownership_transferred, org.deleted |
| Membros | member.invited, member.removed, member.role_changed |
| Funções | role.created, role.updated, role.deleted |
| Engines | engine.created, engine.updated, engine.deleted |
| Chaves de API | api_key.created, api_key.revoked |
| Conteúdo | glossary_item.*, instruction.*, brand_voice.* (apenas operações individuais) |
Como acessar o log#
A entrada Logs de auditoria aparece na barra lateral de Organização apenas quando o entitlement está habilitado para a sua organização. Lá dentro, você encontra:
- Lista filtrável — refine por ator, categoria da ação, tipo de alvo e intervalo de datas. Datas futuras são bloqueadas, e o limite superior é sempre ≥ ao limite inferior.
- Rolagem infinita — eventos mais recentes primeiro; os mais antigos carregam conforme você rola a página.
- Painel de detalhes — clique em qualquer linha para ver todos os metadados, ID da solicitação, IP e user agent.
- Atualizar — busca os eventos mais recentes sem perder sua seleção de filtros. Os filtros e o evento aberto ficam refletidos na URL, então qualquer visualização pode ser compartilhada.
Quem pode visualizar#
O acesso à página é controlado por dois critérios:
- Entitlement — o recurso audit-logs precisa estar habilitado para a organização (plano Enterprise).
- Permissão — a função do usuário precisa incluir
org:view_audit_logs. A função padrão Acesso total já inclui isso; Owners sempre têm essa permissão.
Membros sem essa permissão veem uma página de "sem acesso" em vez da linha do tempo. Membros de uma organização sem esse entitlement veem um paywall.
Se o seu plano Enterprise expirar
Os logs de auditoria fazem parte do mesmo entitlement da camada de RBAC. Eventos antigos continuam no banco de dados, mas a página fica oculta e os endpoints de leitura retornam 403 até que o plano seja restaurado.
Evidência de adulteração#
Os logs de auditoria não são apenas um registro — eles são realmente difíceis de alterar depois do fato.
- Append-only no nível do banco de dados. A migração que instala a tabela executa
REVOKE UPDATE, DELETE, TRUNCATEna função da API. Qualquer caminho de código futuro — bug, novo endpoint, até mesmo injeção de SQL — é rejeitado pelo Postgres antes que consiga alterar uma linha. - Sequência monotônica. Cada linha carrega uma coluna
seqestritamente crescente. Um auditor que examine a sequência pode detectar exclusões pelas lacunas.
Isso é suficiente para controles no estilo SOC 2. Não protege contra um invasor com credenciais diretas do banco de dados de produção — posturas mais robustas (função de proprietário separada, espelho WORM) estão disponíveis mediante solicitação.
Retenção#
Por padrão, os eventos de auditoria ficam armazenados indefinidamente. Janelas de retenção personalizadas — normalmente de 1, 3 ou 7 anos — estão disponíveis no Enterprise. Entre em contato se você precisar de uma política de retenção específica para conformidade ou questionários de segurança.
O que não está coberto#
Alguns limites intencionais da v1 que vale conhecer:
- Emissão best-effort, não transacional. A emissão transacional está no roadmap de curto prazo. O evento de auditoria é gravado depois da ação que ele descreve — não dentro da mesma transação do banco de dados. Em falhas raras (uma ação que dá certo e depois a inserção do evento falha), a ação pode acontecer sem um evento correspondente.
- Alguns tipos de ação ainda não estão conectados. Mudanças na associação de engines, conectar / atualizar / desconectar integração, edições de configuração de modelo, alterações de assinatura de cobrança e operações em massa de conteúdo (upload de CSV,
createMany/updateMany/deleteMany) ainda não geram eventos. O vocabulário de ações já está reservado para que elas apareçam nas categorias de filtro existentes assim que forem conectadas. - Leituras não são auditadas. Visualizar o próprio log de auditoria, navegar pelos logs de solicitações da engine ou baixar um glossário não gera eventos. Apenas ações que alteram o estado geram eventos.
- Ainda não há exportações. Os dados de auditoria são exibidos no dashboard. Exportação em CSV, webhook de SIEM e espelho em S3 estão no roadmap — avise se você precisar disso.
- Não há visualização por escopo de engine. Todos os eventos de auditoria da organização ficam em uma única linha do tempo. Filtre por tipo de alvo ou ID do alvo para restringir o escopo.
- Sem live tail. A lista é atualizada sob demanda ou quando você clica em Atualizar — não há stream via WebSocket.
