ADR-021: métricas de negocio en formato Prometheus, recogidas por la plataforma

Aceptado el 11/11/2026 por Andrés.

Contexto

docs/plataforma/01-forma-de-trabajo-y-capacidades.md dice que las métricas de negocio se emiten con el SDK de OpenTelemetry. El código ya construido hace otra cosa: los servicios Java exponen las métricas con Micrometer en /actuator/prometheus y los adaptadores Node en /metrics, los dos en formato de texto de Prometheus. Y el recolector del demo solo recibe OTLP, así que hoy nadie recoge esas métricas.

El objetivo de la plataforma es que el servicio no implemente telemetría a mano y que el contrato no dependa del lenguaje (ADR-008). Hay dos formas habituales de llevar las métricas de una aplicación al recolector de OpenTelemetry:

Por lectura periódica (pull): la aplicación expone el formato de Prometheus y el recolector la lee con su receptor prometheus. En Kubernetes es la forma más extendida, e Istio la integra: el proxy une las métricas de la aplicación con las suyas en un solo punto de lectura.
Por envío (push): la aplicación envía OTLP, con el SDK o con el puente del agente de Java hacia Micrometer.

Opciones

Opción	A favor	En contra
A. Formato Prometheus en `/metrics`, leído por la plataforma	Es lo que el código ya hace; mismo mecanismo en Java, Node y la malla; el servicio no configura destino ni credenciales	Dos caminos de telemetría: trazas por envío, métricas por lectura
B. SDK de OpenTelemetry en cada servicio	Un solo protocolo	Código de telemetría en cada servicio, distinto por lenguaje; contradice el objetivo de ADR-008
C. Puente del agente de Java hacia Micrometer, por OTLP	Sin código en Java	Solo cubre Java; los adaptadores Node siguen necesitando otro camino

Decisión

Opción A.

Contrato de plataforma, punto 5: el servicio que tiene métricas de negocio las expone en GET /metrics, en formato de texto de Prometheus, con la biblioteca de su marco: Micrometer en Spring Boot (con la ruta de Actuator llevada a /metrics), prom-client o el renderizador de la plantilla en Node.
Demo: el recolector agrega el receptor prometheus y lee /metrics de cada servicio. Las trazas siguen por OTLP desde el agente.
Clúster (F6): el mismo /metrics se declara con las anotaciones de Prometheus e Istio lo une con las métricas del proxy (unión de métricas de Istio).
Etiquetas:
- Ningún dato personal ni de pago (regla 5).
- Ninguna etiqueta de valores sin límite: ni SKU, ni cliente, ni orden. El detalle por SKU va al log.
- Por eso M17 (deriva de inventario) se mide por ubicación, y la lista de SKU con deriva queda en el log de la conciliación.
Puente de Micrometer del agente de Java: queda apagado, para no duplicar series.

Verificación

La prueba de plantillas comprueba que un servicio nuevo de cada plantilla responde GET /metrics en formato de Prometheus.
En el entorno integrado, el recolector muestra las métricas de pricing, inventory y los dos adaptadores.
La prueba de datos personales de telemetría (scripts/lib/otel-pii-probe.js) cubre también las métricas.

Qué se sacrifica

Dos caminos de telemetría que operar: trazas por envío y métricas por lectura.
Una métrica nueva tarda en verse lo que tarde la siguiente lectura (cada 15 segundos en el demo).
Sin SKU como etiqueta, el tablero no responde "qué SKU" directamente: hay que ir al log.