Saltearse al contenido

Monitoreo

Probes

ProbeEndpointComportamiento
LivenessGET /v0/livez{"status":"ok"}. No toma locks ni lee ningún namespace, así que sigue en verde mientras se ejecuta una escritura o una compactación larga. El HEALTHCHECK de la imagen oficial lo usa.
ReadinessGET /v0/health200 con el estado del namespace, o 503 con status: "degraded" cuando el writer está degradado o se alcanzó el tope de memoria.
Ventana de terminal
curl -s localhost:8080/v0/health
# {"status":"ok","namespace":"prod","manifest_version":8,"epoch":0,"writer":"ok",
# "memtable_bytes":0,"memory_resident_bytes":26001408,"memory_max_bytes":0,"memory_pressure":false}

El significado de los campos está en la referencia de la API HTTP. En modo multi-tenant, /:namespace/v0/health abre ese namespace; apunta los probes de nivel de nodo a /v0/livez.

Un ejemplo para Kubernetes:

livenessProbe:
httpGet: { path: /v0/livez, port: 8080 }
periodSeconds: 15
readinessProbe:
httpGet: { path: /v0/health, port: 8080 }
periodSeconds: 10
failureThreshold: 3

Métricas

GET /v0/metrics sirve el formato de texto de Prometheus. No necesita token (igual que los probes); restríngelo a nivel de red si hace falta. Con TLS activado, se sirve por HTTPS en el mismo listener.

scrape_configs:
- job_name: namidb
metrics_path: /v0/metrics
static_configs:
- targets: ["namidb:8080"]

Consultas

MétricaTipoLabelsSignificado
namidb_queries_totalcounterprotocol (http, bolt), status (ok, error)Sentencias ejecutadas
namidb_query_duration_secondshistogramprotocol, kind (read, write)Tiempo real de ejecución (excluye las esperas por backpressure)
namidb_queries_in_flightgaugeSentencias en ejecución ahora
namidb_slow_queries_totalcounterSentencias por encima de --slow-query-threshold

Las llamadas de introspección del esquema por Bolt que hacen las GUIs no se cuentan como consultas.

Writer y compactación

MétricaTipoLabelsSignificado
namidb_writer_lock_wait_secondshistogramTiempo de espera por el lock del writer de un namespace
namidb_writer_lock_timeouts_totalcounterEsperas que llegaron a --writer-lock-timeout (cada una es un 503)
namidb_compactions_totalcountertrigger (periodic, reactive, ddl, admin), statusIntentos de compactación
namidb_compaction_phase_duration_secondshistogramtrigger, phase (prepare, install_wait, install_hold)Tiempo de compactación dividido por fase
namidb_compaction_l0_backlog_sstsgaugetrigger, stage (before, after)Bucket L0 más profundo visto en un límite de compactación
namidb_compaction_ssts_totalcountertrigger, actionArchivos eliminados o escritos por la compactación

Memoria y cachés

MétricaTipoSignificado
namidb_memory_resident_bytesgaugeÚltimo RSS / working set del proceso medido
namidb_memory_max_bytesgaugeTope configurado (0 = desactivado)
namidb_memory_reclaims_totalcounterPasadas de alivio de presión de cachés
namidb_memory_rejected_queries_totalcounterSentencias rechazadas en el tope
namidb_query_memory_limit_bytesgaugePresupuesto de memoria de trabajo por consulta (0 = desactivado)
namidb_query_memory_pool_bytesgaugePool compartido de consultas por kind: capacity, reserved (ahora), peak
namidb_query_memory_stops_totalcounterSentencias en ejecución detenidas con 503 memory_pressure, por reason: pool (el pool compartido estaba lleno) o process (el proceso llegó a su tope). Un 413 query_memory_limit no se cuenta aquí.
namidb_cache_max_bytesgaugeNAMIDB_CACHE_MAX_BYTES
namidb_cache_capacity_bytesgaugeCapacidad asignada a los niveles de caché habilitados
namidb_cache_resident_bytesgaugeBytes actualmente en caché
namidb_range_cache_enabledgaugeSi la caché de rangos de objetos está activada
namidb_range_cache_bytesgaugeCaché de rangos por tier (ram, nvme) y kind (budget, capacity, usage, …)
namidb_range_cache_lookups_totalcounterPor outcome: memory_hit, disk_hit, miss
namidb_range_cache_remote_fetches_totalcounterLecturas al object store después de un miss de caché
namidb_range_cache_events_totalcounterInserciones, rechazos y eventos de corrupción
namidb_range_cache_nvme_io_bytes_totalcounterBytes leídos / escritos en el nivel NVMe

Búsqueda y lookups

MétricaTipoSignificado
namidb_search_index_cache_capacity_bytesgaugePool compartido decodificado vectorial / full-text
namidb_search_index_cache_admission_rejections_totalcounterCuerpos de índice demasiado grandes para el pool, por kind (vector, text)
namidb_search_route_totalcounterBúsquedas servidas por índice o por fallback, por kind y route
namidb_vector_filter_bitmap_searches_totalcounterBúsquedas vectoriales que aplicaron postings de metadatos dentro del índice
namidb_property_lookup_route_totalcounterLookups de propiedades por route (native, fallback)
namidb_tuple_lookup_route_totalcounterLookups de índices compuestos por ruta
namidb_search_workspace_enabled, namidb_search_workspace_bytes, namidb_search_workspace_reservations_totalgauge / counterPool de memoria transitoria de búsqueda

Proceso

MétricaTipoSignificado
namidb_build_info{version="3.3.0"}gaugeSiempre 1
namidb_uptime_secondsgaugeSegundos desde el arranque

Algunas familias solo aparecen después del primer evento que las alimenta (la primera compactación, la primera búsqueda).

Sobre qué alertar

SeñalSugiere
/v0/health en 503 por más de un minutoWriter degradado (bloqueado o con commits fallidos) o tope de memoria alcanzado; revisa writer_error y los logs
rate(namidb_queries_total{status="error"}[5m]) en aumentoErrores de clientes o fallos del servidor; divide por protocolo y luego revisa los logs
p99 de namidb_query_duration_secondsRegresiones de latencia
namidb_compaction_l0_backlog_ssts que se mantiene altoLa compactación se queda atrás respecto de las escrituras; ejecuta admin/compact y revisa el disco del spool
increase(namidb_writer_lock_timeouts_total[5m]) > 0Transacciones de escritura largas o un writer atascado detrás del mantenimiento
increase(namidb_memory_rejected_queries_total[5m]) > 0El tope de memoria está descartando carga; redimensiona las cachés o el contenedor
increase(namidb_query_memory_stops_total[5m]) > 0Consultas en ejecución detenidas por memoria: consultas grandes concurrentes llenan el pool (reason="pool"), o el proceso está en su tope (reason="process")
namidb_search_index_cache_admission_rejections_total en aumentoLos cuerpos de los índices de búsqueda no caben en su pool; sube NAMIDB_SEARCH_INDEX_CACHE_MAX_BYTES

Log de consultas lentas

Las sentencias que igualan o superan --slow-query-threshold (por defecto 1s; 0s desactiva) se registran en WARN, hayan terminado bien o mal:

WARN namidb_server::metrics: slow query protocol="http" kind="read" status="error" elapsed_ms=109 query=MATCH (a:N), (b:N), (c:N) RETURN count(*)

El texto de la sentencia se registra truncado; los parámetros nunca se registran. Un valor escrito inline como literal forma parte del texto, así que pasa los valores sensibles como parámetros.

Consultas en curso

Ventana de terminal
curl -s localhost:8080/v0/admin/queries -H "Authorization: Bearer $ADMIN_TOKEN"
# {"queries":[{"elapsed_ms":2077,"id":8,"namespace":"prod","protocol":"http",
# "statement":"MATCH (a:N), (b:N), (c:N) RETURN count(*)"}]}
curl -s -X POST localhost:8080/v0/admin/queries/8/cancel -H "Authorization: Bearer $ADMIN_TOKEN"
# {"cancelled":8}

Ambos requieren un token de lectura y escritura. Las sentencias se listan de mayor a menor duración, con los espacios en blanco colapsados y el texto truncado a 300 caracteres. Una consulta cancelada se detiene en su siguiente punto de verificación de cancelación, en milisegundos, y su cliente recibe 409 cancelled; una escritura cancelada se revierte. En modo multi-tenant, /:namespace/v0/admin/queries muestra solo ese namespace.

Logs

El servidor escribe logs en stdout mediante tracing. Define el nivel con RUST_LOG (por defecto info), por módulo si hace falta:

Ventana de terminal
RUST_LOG=info,namidb_storage=debug

Al arrancar, el log info registra los deadlines de peticiones resueltos, el modo de autenticación, las capacidades de caché, el tope de memoria y los listeners, que es la forma más rápida de confirmar que una configuración surtió efecto.