Salud y Métricas

Los demonios de Asset Core exponen puntos finales de salud para monitoreo y métricas de Prometheus para observabilidad. Estas señales están diseñadas para mostrar disponibilidad, frescura y retraso, de modo que los operadores puedan detectar problemas antes de que afecten a los usuarios.

Resumen

Ambos demonios de escritura y lectura proporcionan:

Punto final de salud: estado JSON para balanceadores de carga y monitoreo
Punto final de métricas: métricas en formato Prometheus para paneles de control y alertas (deshabilitado por defecto, servido en un oyente dedicado)

Estructura

Puntos finales de salud

Daemon	Endpoint	Descripción
Write	`GET /v1/write/health`	Estado, versión y tiempo de actividad
Read	`GET /v1/read/health`	Disponibilidad más frescura para un espacio de nombres (utiliza `x-assetcore-namespace` cuando no está configurado)

Puntos finales de métricas

Daemon	Endpoint	Format
Escribir	`GET /v1/write/metrics`	Texto de Prometheus (en el oyente de métricas)
Leer	`GET /v1/read/metrics`	Texto de Prometheus (en el oyente de métricas)

Las métricas están deshabilitadas por defecto. Actívelas en daemon-write ([logging] metrics_enabled) y daemon-read ([observability] metrics_enabled), establezca valores distintos para metrics_address y, opcionalmente, permita listas de principios para /v1/write/metrics y /v1/read/metrics. Planee recopilar estos puntos finales temprano en producción para que pueda ver las tendencias de retraso de frescura.

Campos

Respuesta de Salud

{
  "status": "ready",
  "freshness": {
    "namespace": 1,
    "world_seq": 128,
    "commit_log_world_seq": 130,
    "lag": 2,
    "lag_ms": 250
  }
}

Campo	Descripción
`status`	Leer: `starting`, `ready`, `degraded`; Escribir: `healthy`
`version`	Cadena de versión del daemon solo para escritura
`api_version`	Cadena de versión de la API solo para escritura
`build_git_sha`	SHA del commit de Git solo para escritura cuando esté disponible
`uptime_secs`	Segundos desde el inicio del proceso solo para escritura
`freshness`	Metadatos de frescura solo para lectura del espacio de nombres

Métricas Clave

Escribir daemon

Métrica	Tipo	Descripción
`ingress_requests_total`	Contador	Total de solicitudes de ingreso por ruta/resultados
`ingress_request_duration_seconds`	Histograma	Latencia de solicitudes de ingreso
`commit_duration_seconds`	Histograma	Latencia de compromiso de extremo a extremo
`ingress_queue_depth`	Medidor	Elementos en espera en la cola
`ingress_inflight`	Medidor	Solicitudes en proceso
`commit_log_end_seq`	Medidor	Última secuencia comprometida
`commit_log_driver_lag_events`	Medidor	Retraso del controlador del registro de compromisos en eventos

Leer daemon

Métrica	Tipo	Descripción
`http_requests_total`	Contador	Total de solicitudes HTTP por ruta/resultado
`http_request_duration_seconds`	Histograma	Latencia de solicitudes HTTP
`read_checkpoint_seq`	Medidor	Secuencia aplicada
`read_commit_log_end_seq`	Medidor	Secuencia de registro de confirmaciones observada
`freshness_lag_events`	Medidor	Eventos detrás del registro de confirmaciones
`freshness_lag_ms`	Medidor	Milisegundos detrás del registro de confirmaciones
`snapshot_publish_duration_seconds`	Histograma	Tiempo de publicación de instantáneas

Ejemplos

Verificar la Salud de Escritura

curl -H "Authorization: Bearer $ASSETCORE_ADMIN_TOKEN" \
  http://localhost:8080/v1/write/health | jq .

Verificar la Frescura de Lectura

curl -H "Authorization: Bearer $ASSETCORE_READ_TOKEN" \
  http://localhost:8081/v1/read/namespaces/5001/freshness | jq .

Métricas de Scrape

Agrega a tu configuración de Prometheus:

scrape_configs:
  - job_name: 'assetcore-write'
    static_configs:
      - targets: ['localhost:9100']
    metrics_path: '/v1/write/metrics'

  - job_name: 'assetcore-read'
    static_configs:
      - targets: ['localhost:9101']
    metrics_path: '/v1/read/metrics'

Ejemplos de Consultas de Prometheus

Tasa de solicitud:

rate(ingress_requests_total[5m])

Latencia P99:

histogram_quantile(0.99, rate(ingress_request_duration_seconds_bucket[5m]))

Lectura del retraso del daemon:

freshness_lag_events

Tasa de error:

rate(http_requests_total{outcome!="success"}[5m])

Ejemplos de Alertas

groups:
  - name: assetcore
    rules:
      - alert: HighReadLag
        expr: freshness_lag_events > 100
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Read daemon is behind commit log"

      - alert: WriteQueueFull
        expr: ingress_queue_depth > 900
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Write queue approaching capacity"

Conceptos básicos de implementación - Ejecución de demonios
Frescura y Repetición - Comprendiendo el retraso
API HTTP - Referencia de endpoints