101 lines
6.4 KiB
Markdown
101 lines
6.4 KiB
Markdown
# Auditoría y operación (T15)
|
||
|
||
## Historial
|
||
|
||
`GET /api/v1/requests/{id}/history` requiere REQUEST_API_ENABLED y JWT válido.
|
||
Aplica la misma propiedad y businessScope que GET de solicitud; FLOW_ADMIN y
|
||
EXECUTION_OPERATOR no tienen un bypass para consultar historial ajeno. Un recurso
|
||
ajeno/inexistente responde 404. La respuesta cumple HistoryPage y usa no-store.
|
||
|
||
Filtros opcionales: kind, executionId, from inclusivo y to exclusivo (UTC terminado
|
||
en Z). limit por defecto 50, rango 1–100. Orden ascendente por (createdAt,id),
|
||
mediante keyset; cursor opaco de máximo 2000 caracteres ligado a solicitud y filtros.
|
||
Se permite cambiar limit conservando los demás filtros. Al terminar se omite
|
||
nextCursor. Cursor inválido o usado con otros filtros devuelve 400.
|
||
|
||
El cursor representa posición, no autorización ni una credencial firmada. Cada
|
||
página vuelve a autorizar el recurso; modificar una posición nunca amplía su acceso.
|
||
Los inserts concurrentes pueden aparecer en páginas posteriores; no es una foto
|
||
transaccional de toda la navegación. Reiniciar desde from permite releer períodos
|
||
cuando hay transacciones que confirmaron tarde. El consumidor deduplica por id.
|
||
|
||
Proyección de detail permitida: correlationId, transitionId, acceptedRevision,
|
||
ruleIds, reasonCodes, actionIds, hitPolicy, code, actionId, delayMs, mode y resolutionId.
|
||
Se omiten datos de entrada, resultados completos, tokens y evidencia del operador.
|
||
actorSubject se entrega únicamente al propietario autorizado. Nuevas transiciones
|
||
guardan reasonCodes de resultados de acciones cuando existen; no se reconstruyen
|
||
razones para auditorías históricas que no las contenían.
|
||
|
||
Se mantienen las escrituras atómicas T06–T12 y triggers append-only V2. No hay una
|
||
segunda escritura de auditoría posterior al commit ni una migración nueva. El rol
|
||
runtime no modifica ni elimina historial. Retención/eliminación requiere una política
|
||
de datos aprobada y procedimiento privilegiado aparte; este servicio no borra
|
||
auditoría automáticamente ni interpreta un TTL como permiso de borrado.
|
||
|
||
## Métricas
|
||
|
||
`/actuator/metrics` y `/actuator/metrics/{name}` requieren EXECUTION_OPERATOR y
|
||
businessScope incluido en ADMIN_BUSINESS_SCOPES. No dependen de habilitar edición
|
||
de flujos. Actuator restante está denegado salvo las tres rutas públicas de salud.
|
||
No se agrega servidor Prometheus ni dependencia nueva; Micrometer/Actuator ya están
|
||
incluidos en el servicio.
|
||
|
||
| Nombre | Tipo/etiquetas | Significado |
|
||
| --- | --- | --- |
|
||
| orchestrator.commands | Counter: command=create/event; result=accepted/rejected/error | Respuestas HTTP de comandos, incluidos replays; accepted es 2xx, error 5xx y rejected resto |
|
||
| orchestrator.executions | Gauge: state fijo | Filas durables por estado técnico, compartidas entre réplicas |
|
||
| orchestrator.pending.oldest.seconds | Gauge sin etiquetas | Edad DB del PENDING más antiguo; cero sin pendientes |
|
||
| orchestrator.leases.expired | Gauge sin etiquetas | RUNNING con lease vencido; no implica efecto externo duplicado |
|
||
| orchestrator.queue.sample.available | Gauge sin etiquetas | 1 muestra SQL disponible; 0 fallo; demás gauges NaN al fallar |
|
||
| orchestrator.integration.duration | Timer: integration, result=completed/failed/error | Tiempo del adapter HTTP, incluido contrato/mapeo; solo claves del catálogo/rutas permitidas |
|
||
|
||
Los gauges se consultan bajo demanda y comparten una muestra SQL por proceso de
|
||
5 segundos; query timeout 3 segundos. Son estados actuales, no contadores históricos
|
||
de transiciones. RECONCILIATION_REQUIRED expone conciliaciones pendientes y RETRY_WAIT
|
||
reintentos programados. No hay etiquetas por UUID, sujeto, ámbito, URL, perfil,
|
||
excepción libre o datos de proveedor. Las claves de integración pertenecen a
|
||
configuración confiable. Contadores/timers locales se reinician con el proceso;
|
||
no son el ledger durable. Para varias réplicas no sumar gauges de la misma DB.
|
||
|
||
## Logs y correlación
|
||
|
||
El filtro genera X-Correlation-Id; no confía en uno suministrado por el cliente.
|
||
Comandos registran tipo, resultado HTTP, código de estado, correlación y duración.
|
||
Worker registra requestId, executionId, flowId, versión; acciones añaden actionId,
|
||
intento, resultado técnico y duración. `phase=committed` se emite después del commit.
|
||
Un log de acción completada puede preceder un rollback: consultar ejecución/historial
|
||
para el resultado durable. No registra payload, documento, sujeto, token, score,
|
||
evidencia ni excepción con body de proveedor. correlationId de EVENT_ACCEPTED enlaza
|
||
HTTP con executionId del historial y del worker; el adapter propaga executionId
|
||
como X-Correlation-Id estable entre intentos. Las decisiones y razones quedan en
|
||
auditoría restringida, no en logs.
|
||
|
||
## Salud y apagado
|
||
|
||
`/actuator/health/liveness` consulta disponibilidad del proceso, sin DB/proveedores.
|
||
`/actuator/health/readiness` añade PostgreSQL; falla 503 cuando DB no está disponible.
|
||
`/actuator/health` es salud agregada. Las rutas públicas omiten detalles/componentes.
|
||
No se llama a clientes/documentos/buró para determinar salud.
|
||
|
||
Spring usa server.shutdown=graceful y 30 s por fase. El worker deja de reclamar,
|
||
cierra el poller (hasta 2 s) y conserva heartbeats mientras drena trabajos durante
|
||
WORKER_SHUTDOWN_SECONDS (1–20, predeterminado 20). Al agotar, interrumpe trabajos y
|
||
espera 1 s adicional; cancela renovaciones. Los adapters deben respetar interrupción
|
||
y sus límites de tiempo. Una operación no cooperativa puede seguir hasta su timeout;
|
||
no se presume cancelación de un efecto externo. Cola/checkpoints permanecen durables
|
||
y se recuperan por lease/fencing y conciliación T12. No se liberan leases por apagar.
|
||
Compose mantiene stop_grace_period=40s para la JVM y PostgreSQL externo.
|
||
|
||
## Verificación
|
||
|
||
ObservabilityIT usa API/JWT real, esquema y rol temporales en orquestador_test:
|
||
historial/ACL/filtros/cursor/empates, métricas SQL, Actuator y logs con sentinelas.
|
||
Cierra únicamente su propio pool para demostrar readiness 503/liveness 200.
|
||
ObservabilityTest usa latches y worker real con store controlado para drenaje,
|
||
renovación e interrupción dentro del presupuesto; HTTP loopback prueba timers.
|
||
WorkerIT conserva pruebas reales de rollback de auditoría, recuperación y fencing.
|
||
No es una prueba de despliegue Docker ni de caída de PostgreSQL de producción.
|
||
|
||
Fuentes de API: [Micrometer](https://docs.micrometer.io/micrometer/reference/concepts/meters.html)
|
||
y [Actuator Health](https://docs.spring.io/spring-boot/api/rest/actuator/health.html).
|