Monitoreo

El arquetipo configura una superficie de monitoreo basada en una allowlist de endpoints actuator y agrega tres componentes propios para observar las bandejas del patron outbox/inbox: un endpoint custom, cuatro HealthIndicator y dos metricas Micrometer. Las decisiones detras de esa configuracion se discuten en Decisiones de monitoreo.

Configuracion por defecto

Todas las propiedades viven bajo management.* en el application.yaml del proyecto generado.

Propiedad Valor Notas

management.endpoints.web.exposure.include

health, info, loggers, metrics, message-boxes

Allowlist. Cualquier otro endpoint que Spring auto-configure queda fuera. La semantica de los endpoints estandar vive en la doc de Spring Boot Actuator.

management.endpoint.health.show-details

when-authorized

Idem show-components. Los tres valores posibles y su comportamiento estan en Spring health endpoint.

management.endpoint.health.probes.enabled

true

Activa /actuator/health/liveness y /actuator/health/readiness. Por defecto cada path expone solo livenessState o readinessState — los demas indicadores no participan. La composicion de los grupos esta en Spring Kubernetes probes.

management.endpoint.health.cache.time-to-live

10s

Cachea el resultado de /actuator/health para amortizar los probes de K8s.

management.endpoint.info.cache.time-to-live

300s

info es estatico (build, git) — TTL alto reduce overhead sin riesgo de servir datos viejos.

management.health.livenessstate.enabled

true

Registra livenessState en el agregado de health (ademas de exponerlo en /health/liveness).

management.health.readinessstate.enabled

true

Idem para readinessState.

management.endpoint.health.message-boxes.stuck-threshold

PT5M

Default global para las cuatro bandejas. Override por bandeja: ver abajo.

Los endpoints que Spring auto-configura y no estan en la allowlist — env, beans, heapdump, threaddump, mappings, configprops, scheduledtasks, shutdown — no responden. El motivo de excluirlos esta en Decisiones de monitoreo > allowlist.

Endpoint /actuator/message-boxes

Endpoint custom — no provisto por Spring — con estadisticas de las cuatro bandejas del patron outbox/inbox: events.outbox, events.inbox, commands.outbox, commands.inbox.

Estructura de la respuesta

{
  "events": {
    "outbox": {
      "pending":          12,
      "failed":           0,
      "stuck":            0,
      "stuckThreshold":   "PT5M",
      "oldestPendingAt":  "2026-04-29T20:31:47.812Z",
      "lastProcessedAt":  "2026-04-29T20:42:03.117Z"
    },
    "inbox":  { ... }
  },
  "commands": {
    "outbox": { ... },
    "inbox":  { ... }
  }
}

Campos por bandeja

Campo Significado

pending

Mensajes en estado PENDING (encolados, aun no procesados).

failed

Mensajes en estado FAILED (excedieron max-retries). Quedan en la tabla para inspeccion manual.

stuck

Mensajes PENDING cuyo oldestPendingAt es anterior a now - stuckThreshold. Senal de que el procesador esta atascado o no esta corriendo.

stuckThreshold

Duration ISO-8601 efectiva para esta bandeja, despues de aplicar override y default global.

oldestPendingAt

Timestamp del mensaje pendiente mas antiguo. null si no hay pendientes.

lastProcessedAt

Timestamp del ultimo mensaje procesado exitosamente. null si nunca se proceso ninguno.

Para uso operacional (curl, override de threshold) ver Inspeccionar las bandejas de mensajeria.

Indicadores de health custom

MessageBoxHealthIndicator registra cuatro indicadores que se suman a los que Spring auto-configura, accesibles en /actuator/health con un usuario autorizado:

Indicador Que reporta

eventsOutbox, eventsInbox, commandsOutbox, commandsInbox

UP si la consulta a la bandeja responde, DOWN si la consulta lanza excepcion. Los contadores (pending, failed, stuck) viajan en el campo details.

Estos indicadores son una probe del read path — confirman que la tabla se puede leer. Una bandeja con miles de mensajes pendientes sigue siendo UP mientras la query funcione.

El backlog se observa via las metricas Micrometer o el endpoint /actuator/message-boxes, no via /actuator/health. La razon esta en probes y health desacoplados.

Metricas custom

MessageBoxesMeterBinder registra dos metricas Micrometer, una por estado relevante. Cada una se etiqueta con type y box, generando 4 x 2 = 8 series totales:

Metrica Que mide Tags

messagebox.pending

Cantidad de mensajes en PENDING por bandeja

type ∈ {events, commands}, box ∈ {outbox, inbox}

messagebox.failed

Cantidad de mensajes en FAILED por bandeja

type ∈ {events, commands}, box ∈ {outbox, inbox}

Consulta directa: /actuator/metrics/messagebox.pending (todas las series agregadas) o /actuator/metrics/messagebox.pending?tag=type:events&tag=box:outbox para una serie especifica.

No hay metrica messagebox.stuck. stuck depende de stuckThreshold y se calcula al vuelo en cada query — exponerlo como gauge requeriria evaluar el threshold en cada scrape, sin valor agregado frente a derivar la alerta de messagebox.pending con duracion sostenida.

Override del stuck-threshold por bandeja

Cada bandeja admite un valor propio bajo management.endpoint.health.message-boxes.<type>.<box>.stuck-threshold, donde <type> ∈ {events, commands} y <box> ∈ {outbox, inbox}.

Resolucion: override por bandeja → default global → fallback PT5M hardcoded en MessageBoxesHealthProperties. Para ejemplos concretos de override ver Inspeccionar las bandejas.

Referencias