openaudit-observability

Implementação oficial de observabilidade do ecossistema OpenAudit Brasil.

Este repositório entrega kits reutilizáveis (Node e Python) para que serviços e CLIs emitam:

• logs estruturados (JSON), com campos padronizados e redaction de PII
• correlação via request_id (HTTP) e run_id (execuções/pipeline)
• métricas padronizadas (quando habilitadas)
• traces via OpenTelemetry (opcional)

Source of truth: os contratos de logs/telemetria são definidos no openaudit-core-contracts.
Este repo implementa bibliotecas/middlewares para emitir telemetria compatível.

---

Índice

• Objetivo
• O que este repositório é (e não é)
• Arquitetura e integração
• Pacotes disponíveis
  • Node (Fastify/Express)
  • Python (CLI/pipelines)
• Formato de logs
• PII / Redaction (obrigatório)
• Correlação: request_id e run_id
• Métricas
• Traces (OpenTelemetry)
• Como executar (dev)
• Testes
• Exemplos
• Diretrizes de desenvolvimento
• Compatibilidade com core-contracts
• Links oficiais
• Licença

---

Objetivo

Padronizar e facilitar a observabilidade no OpenAudit Brasil para:

1. Auditoria operacional: provar "o que rodou, quando e como".
2. Debug e confiabilidade: localizar falhas por etapa (search, ingest, export, QA…).
3. Segurança: impedir vazamento de PII em logs.
4. Plug-and-play: todo novo serviço/CLI adota telemetria sem reinventar padrão.

---

O que este repositório é (e não é)

✅ É

• SDKs / middlewares de observabilidade para Node e Python.
• Implementação do padrão de logs/telemetria definido pelo core-contracts.
• Ferramentas para:
  • gerar/propagar IDs de correlação
  • emitir logs JSON compatíveis com schema
  • medir latência/duração
  • expor métricas (opcional)
  • emitir traces OTel (opcional)

❌ Não é

• Uma stack de monitoramento (Grafana/ELK/Datadog).
• Um serviço central.
• Um banco de auditoria (isso é outro componente do roadmap de análise).
• Um lugar para "guardar logs".

---

Arquitetura e integração

• openaudit-core-contracts define:
  • schemas/observability/log_event.schema.json
  • registry de métricas e convenções
• openaudit-observability:
  • emite logs/métricas/traces seguindo os contratos
  • testa em CI que o output valida contra core-contracts

Consumidores típicos:

• openaudit-search-api (Node): request logging + search events
• openaudit-entity-catalog (Python CLI): stages de build/export/QA com run_id

---

Pacotes disponíveis

Node (Fastify/Express)

Objetivo: instrumentar APIs HTTP (ex.: search-api) com:

• request_id automático
• logs por request e eventos internos
• redaction de campos sensíveis
• métricas e OTel opcionais

Recursos esperados

• plugin Fastify
• middleware Express (opcional)
• helpers:
  • logEvent(name, data)
  • withSpan(name, fn) (se OTel habilitado)

---

Python (CLI/pipelines)

Objetivo: instrumentar CLIs e pipelines (ex.: entity-catalog) com:

• run_id por execução
• "stages" com duração
• logs de hashes e contagens de artefatos
• redaction de campos sensíveis

Recursos esperados

• run_context(...) (context manager)
• stage(name) (sub-context)
• helpers para:
  • artifact_hash(file)
  • rows_count(...)

---

Formato de logs

Padrão

• JSON Lines (1 evento por linha)
• Compatível com o schema do core-contracts

Campos mínimos (conceito)

• timestamp
• level
• service.name, service.version
• env
• event.name
• correlation.request_id (para HTTP)
• correlation.run_id (para pipeline)
• duration_ms (quando aplicável)
• status (success|error|timeout|skipped)
• data (payload estruturado, sem PII)

Exemplo (search-api)

{
  "timestamp": "2026-02-28T20:10:00Z",
  "level": "info",
  "service": { "name": "openaudit-search-api", "version": "0.1.0" },
  "env": "dev",
  "event": { "name": "catalog.search" },
  "correlation": { "request_id": "req_123", "run_id": null },
  "data": {
    "query_hash": "sha256:...",
    "catalog_version": "2026-02-28",
    "limit": 10,
    "offset": 0,
    "result_count": 8,
    "cache_hit": false
  },
  "duration_ms": 21,
  "status": "success"
}

---

PII / Redaction (obrigatório)

Este repo deve assumir que:

• qualquer desenvolvedor pode acidentalmente logar dado sensível

Por isso:

• redaction é default-on no Node e no Python

• logs jamais devem conter:

  • q bruto (consulta textual)
  • CPF, e-mail, telefone
  • headers sensíveis (Authorization, Cookie)
  • payloads externos completos

Estratégia

• allowlist de campos no data, quando possível

• denylist agressiva de paths conhecidos

• hash/mascaramento em vez de valor raw:

  • query_hash em vez de q

---

Correlação: request_id e run_id

request_id (HTTP)

• gerado se não existir
• retornado em header X-Request-Id
• logado em correlation.request_id

run_id (pipeline/execução)

• gerado por CLI/pipeline
• propagado para stages e eventos
• logado em correlation.run_id

Regra: qualquer evento de pipeline deve incluir run_id.

---

Métricas

Métricas são opcionais no MVP, mas o kit deve suportar:

• http_requests_total
• http_request_duration_ms
• cache_hit_total
• search_candidates_returned
• pipeline_stage_duration_ms{stage=...} (Python CLI/pipelines)

Recomendação:

• expor /metrics (Prometheus) apenas quando habilitado por config

---

Traces (OpenTelemetry)

OpenTelemetry é opcional e deve ser feature-flag.

Quando usar

• quando houver pipeline de análise (fase 2+)
• quando debugging exigir rastreio por etapa

Convenções

• nome de spans padronizados:

  • http.server
  • catalog.search
  • pipeline.stage.<name>

• atributos essenciais:

  • request_id, run_id
  • catalog_version
  • source (quando aplicável)

---

Como executar (dev)

Este repo é multi-package (Node + Python).

Node package (exemplo)

cd packages/node
npm install
npm test

Python package (exemplo)

cd packages/python
python -m venv .venv
source .venv/bin/activate
pip install -e .
pytest

Ajuste para pnpm/uv/poetry se padronizar na organização.

---

Testes

O CI deve cobrir:

1. Schema compliance

• Eventos emitidos pelos exemplos devem validar contra os JSON Schemas do core-contracts.

2. Redaction

• Testes garantindo que paths proibidos são removidos/mascarados.

3. Correlation

• request_id sempre presente em logs de request
• run_id sempre presente em logs de pipeline/stages

4. Métricas (quando habilitadas)

• contador incrementa
• latência registrada

5. OTel (quando habilitado)

• spans criados
• atributos essenciais presentes

---

Exemplos

Este repo deve incluir exemplos executáveis:

• examples/node-fastify-search-api/
• endpoint /search
• logs e métricas habilitados
• examples/python-cli-entity-catalog/
• build → validate → export emitindo logs de stages

---

Diretrizes de desenvolvimento

Regras obrigatórias

• Não adicionar logs com PII (mesmo em dev).
  • Se for necessário debug:
  • use hashes, contagens e IDs
  • nunca valores brutos sensíveis
• Qualquer mudança de formato de log deve:
  • atualizar core-contracts
  • atualizar exemplos
  • atualizar testes

Padrões de eventos (recomendado)

• catalog.search
• cache.hit / cache.miss
• catalog.build
• catalog.qa
• catalog.export

---

Compatibilidade com core-contracts

Este repo depende dos contratos do:

• https://github.com/OpenAudit-Brasil/openaudit-core-contracts (exemplo de nome)

Integração recomendada:

• testes importam os JSON Schemas do core-contracts
• falha de validação = CI falha

---

Links oficiais

Documentação normativa (fonte de verdade):

• https://github.com/OpenAudit-Brasil/About

Roadmap:

• https://github.com/OpenAudit-Brasil/About/blob/main/ROADMAP.md

---

Licença

Licença oficial:

• https://github.com/OpenAudit-Brasil/About/blob/main/LICENSE