Observabilidad, resiliencia y auditoría
15.1 OpenTelemetry por defecto
- Traces: W3C Trace Context (propagado vía Pub/Sub attributes
traceparent+tracestate). - Metrics: Micrometer + OTLP exporter; Prometheus-compatible.
- Logs: Estructurados JSON (Logback + Logstash encoder). Campos obligatorios:
requestId,eventId,partnerId,companyId,sourceSystem,trace_id,span_id,severity.
15.2 Métricas clave (Prometheus naming: nexus_*)
| Métrica | Tipo | Labels recomendadas | Nota |
|---|---|---|---|
nexus_purchase_orders_received_total | Counter | partnerId, documentType, sourceSystem | |
nexus_purchase_orders_created_total | Counter | partnerId | |
nexus_purchase_orders_failed_total | Counter | partnerId, errorCategory | |
nexus_validation_failed_total | Counter | partnerId, ruleCode | Alto valor para alertamiento spikes |
nexus_processing_duration_seconds | Histogram | partnerId, stage (receive/validate/queue/process/created) | |
nexus_oracle_fusion_latency_seconds | Histogram | partnerId, operation=create_po | |
nexus_retry_total | Counter | partnerId, reason | |
nexus_dlq_messages_total | Counter | partnerId, reason, originalTopic | |
nexus_outbox_lag_seconds | Gauge | (now - min created_at de pending) | |
nexus_outbox_published_total | Counter | ||
nexus_rules_evaluation_duration_seconds | Histogram | partnerId |
Etiquetas de alta cardinalidad
No incluir requestId, externalReference ni eventId como labels de métricas. Mantener dimensionalidad baja (partnerId, status, ruleCode, errorCategory).
15.3 Dashboards recomendados
- Executive / negocio: OC creadas por partner en el tiempo (% éxito vs fallo).
- Pipeline E2E: Latencia percentiles p50/p95/p99 (received → created).
- Validation Engine: reglas con más fallos / duración.
- Pub/Sub + DLQ: backlog, ack deadlines, DLQ rate.
- Oracle Fusion: latencias + errores por categoría.
- Outbox lag: pending events + duración.
- Seguridad: autenticaciones fallidas, rate limits hits, scopes denegados.
15.4 Alertas (alertamiento TBD umbrales SLA)
- Outbox lag > TBD 5 minutos.
- DLQ rate > 0 en 10m (alerta inmediata).
nexus_purchase_orders_failed_total> umbral.- Latencia Fusion p99 > TBD 60s.
- Errores AUTHENTICATION / AUTHORIZATION en spikes (rotación secrets / configuración).
- Health checks: Purchase Order API / Status / Worker (Spring Actuator).
15.5 Resilience4j — Dónde aplica cada patrón
| Patrón | Dónde se usa |
|---|---|
| Timeout | Todo outbound: Fusion REST calls, Pub/Sub publish, DB queries lentas TBD |
| Retry | Pub/Sub publish; Fusion TEMPORARY_ERRORS (3 attempts); DB transacciones deadlock puntuales |
| Circuit Breaker | Fusion REST calls por partner (CB por client) |
| Bulkhead | Fusion REST por partner (número máximo de llamadas concurrentes) |
| Rate Limiting | Gateway por partner; y opcionalmente endpoints internos si requieren |
| Idempotency | Full stack (ingesta, publish, consume, ERP) |
| DLQ | Pub/Sub subscription + manual reprocess |
| Transactional Outbox | Cada publicación de evento de dominio |
15.6 Auditoría: tipos de eventos (audit_event.event_type)
REQUEST_RECEIVED
REQUEST_IDEMPOTENT_HIT
VALIDATION_STARTED
VALIDATION_COMPLETED
VALIDATION_FAILED
REQUEST_QUEUED
OUTBOX_PUBLISHED
OUTBOX_PUBLISH_FAILED
PROCESSING_STARTED
ORACLE_REQUEST_SENT
ORACLE_RESPONSE_RECEIVED
PURCHASE_ORDER_CREATED
RETRY_REQUESTED (manual)
RETRY_AUTO_TRIGGERED
REQUEST_FAILED
REQUEST_REJECTED
STATUS_QUERIED
RULE_CREATED
RULE_UPDATED
RULE_STATUS_CHANGED
PARTNER_CONFIG_CREATED
PARTNER_CONFIG_UPDATED
Cada audit_event incluye: actor, requestId, component, detail JSONB, at.
15.7 Trazabilidad distribuida
- Header entrada:
traceparent(W3C) +X-Request-Id(propagado y validado). - Spans:
POST /purchase-orders,validate:purchase-order,db:tx-outbox,outbox:publish,pubsub:deliver,oracle:create-po. baggageOTEL:partnerId,companyId,sourceSystem,requestId.