Monitoreo
Probes
| Probe | Endpoint | Comportamiento |
|---|---|---|
| Liveness | GET /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. |
| Readiness | GET /v0/health | 200 con el estado del namespace, o 503 con status: "degraded" cuando el writer está degradado o se alcanzó el tope de memoria. |
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: 15readinessProbe: httpGet: { path: /v0/health, port: 8080 } periodSeconds: 10 failureThreshold: 3Mé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étrica | Tipo | Labels | Significado |
|---|---|---|---|
namidb_queries_total | counter | protocol (http, bolt), status (ok, error) | Sentencias ejecutadas |
namidb_query_duration_seconds | histogram | protocol, kind (read, write) | Tiempo real de ejecución (excluye las esperas por backpressure) |
namidb_queries_in_flight | gauge | Sentencias en ejecución ahora | |
namidb_slow_queries_total | counter | Sentencias 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étrica | Tipo | Labels | Significado |
|---|---|---|---|
namidb_writer_lock_wait_seconds | histogram | Tiempo de espera por el lock del writer de un namespace | |
namidb_writer_lock_timeouts_total | counter | Esperas que llegaron a --writer-lock-timeout (cada una es un 503) | |
namidb_compactions_total | counter | trigger (periodic, reactive, ddl, admin), status | Intentos de compactación |
namidb_compaction_phase_duration_seconds | histogram | trigger, phase (prepare, install_wait, install_hold) | Tiempo de compactación dividido por fase |
namidb_compaction_l0_backlog_ssts | gauge | trigger, stage (before, after) | Bucket L0 más profundo visto en un límite de compactación |
namidb_compaction_ssts_total | counter | trigger, action | Archivos eliminados o escritos por la compactación |
Memoria y cachés
| Métrica | Tipo | Significado |
|---|---|---|
namidb_memory_resident_bytes | gauge | Último RSS / working set del proceso medido |
namidb_memory_max_bytes | gauge | Tope configurado (0 = desactivado) |
namidb_memory_reclaims_total | counter | Pasadas de alivio de presión de cachés |
namidb_memory_rejected_queries_total | counter | Sentencias rechazadas en el tope |
namidb_query_memory_limit_bytes | gauge | Presupuesto de memoria de trabajo por consulta (0 = desactivado) |
namidb_query_memory_pool_bytes | gauge | Pool compartido de consultas por kind: capacity, reserved (ahora), peak |
namidb_query_memory_stops_total | counter | Sentencias 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_bytes | gauge | NAMIDB_CACHE_MAX_BYTES |
namidb_cache_capacity_bytes | gauge | Capacidad asignada a los niveles de caché habilitados |
namidb_cache_resident_bytes | gauge | Bytes actualmente en caché |
namidb_range_cache_enabled | gauge | Si la caché de rangos de objetos está activada |
namidb_range_cache_bytes | gauge | Caché de rangos por tier (ram, nvme) y kind (budget, capacity, usage, …) |
namidb_range_cache_lookups_total | counter | Por outcome: memory_hit, disk_hit, miss |
namidb_range_cache_remote_fetches_total | counter | Lecturas al object store después de un miss de caché |
namidb_range_cache_events_total | counter | Inserciones, rechazos y eventos de corrupción |
namidb_range_cache_nvme_io_bytes_total | counter | Bytes leídos / escritos en el nivel NVMe |
Búsqueda y lookups
| Métrica | Tipo | Significado |
|---|---|---|
namidb_search_index_cache_capacity_bytes | gauge | Pool compartido decodificado vectorial / full-text |
namidb_search_index_cache_admission_rejections_total | counter | Cuerpos de índice demasiado grandes para el pool, por kind (vector, text) |
namidb_search_route_total | counter | Búsquedas servidas por índice o por fallback, por kind y route |
namidb_vector_filter_bitmap_searches_total | counter | Búsquedas vectoriales que aplicaron postings de metadatos dentro del índice |
namidb_property_lookup_route_total | counter | Lookups de propiedades por route (native, fallback) |
namidb_tuple_lookup_route_total | counter | Lookups de índices compuestos por ruta |
namidb_search_workspace_enabled, namidb_search_workspace_bytes, namidb_search_workspace_reservations_total | gauge / counter | Pool de memoria transitoria de búsqueda |
Proceso
| Métrica | Tipo | Significado |
|---|---|---|
namidb_build_info{version="3.3.0"} | gauge | Siempre 1 |
namidb_uptime_seconds | gauge | Segundos 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ñal | Sugiere |
|---|---|
/v0/health en 503 por más de un minuto | Writer 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 aumento | Errores de clientes o fallos del servidor; divide por protocolo y luego revisa los logs |
p99 de namidb_query_duration_seconds | Regresiones de latencia |
namidb_compaction_l0_backlog_ssts que se mantiene alto | La 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]) > 0 | Transacciones de escritura largas o un writer atascado detrás del mantenimiento |
increase(namidb_memory_rejected_queries_total[5m]) > 0 | El tope de memoria está descartando carga; redimensiona las cachés o el contenedor |
increase(namidb_query_memory_stops_total[5m]) > 0 | Consultas 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 aumento | Los 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
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:
RUST_LOG=info,namidb_storage=debugAl 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.