Esta página describe Calíope 1.7, la versión que estoy construyendo ahora mismo. La 1.6 está en la App Store para Mac, iPad, iPhone, Apple Watch, Apple TV y Apple Vision Pro. El changelog dice en qué versión llegó cada función.
Añade un botón «Abrir en Calíope» a cada tema. Sólo funciona con la app instalada.
Cómo buscar en Query DSL, SQL, ES|QL o PPL, cómo se pagina, qué enseñan las agregaciones y «explicar», y por qué la Consulta sólo lee.
Dónde está: Espacio de Trabajo › Herramientas › Consulta
Aplica a:ElasticsearchOpenSearch
La Consulta manda al clúster lo que escribes, por la sesión abierta. Ejecutar (⌘↩) la ejecuta y Detener (⌘.) deja de esperar la respuesta: lo que el servidor ya empezó puede terminar igual.
El lenguaje
El selector de lenguaje de la barra enseña sólo los lenguajes del producto de la sesión. Los dos tienen Query DSL —el cuerpo JSON de _search— y SQL.
Elasticsearch
Elasticsearch tiene además ES|QL, su lenguaje de tuberías: FROM demo_productos | WHERE precio > 40 | LIMIT 10.
OpenSearch
OpenSearch tiene además PPL, su lenguaje de tuberías: source=demo_productos | where precio > 40 | head 10.
Query DSL
El cuerpo va entero a _search de los índices escritos en Índices: vacío son todos, y varios van separados por comas. Elegir un índice los lista. El menú Página: 50 dice cuántos documentos trae cada página (50 si no lo cambias), salvo que el cuerpo lleve su propio size, que manda. Un JSON roto lo rechaza el servidor, y el error dice dónde está la errata: la línea y la columna, o el byte del cuerpo.
Las páginas y el total Siguiente página pide la siguiente. Si la búsqueda ordena (sort), va por search_after, que sigue desde el último documento recibido y no tiene límite. Si no ordena, va por from, que el servidor corta en 10 000 documentos, y la vista lo avisa. El servidor deja de contar en 10 000 y el total sale como «10 000 o más»; Total exacto le pide contarlos todos (track_total_hits), a costa de tiempo.
Lo que se ve Documentos enseña cada documento plegado en una línea, con su puntuación; ábrelo para ver su _source entero. Tabla pone los campos en columnas, con los objetos anidados aplanados. Si el cuerpo lleva aggs, Agregaciones salen debajo, como árbol. Explicar, en cada documento, le pregunta al servidor por qué casa con la búsqueda (_explain) y enseña cómo calculó su puntuación.
SQL, ES|QL y PPL
En estos lenguajes el índice va dentro de la consulta (FROM, source=), y la respuesta es una tabla. La cabecera de cada columna lleva el tipo que declara el servidor, que no siempre coincide entre lenguajes ni entre productos. Si la licencia del clúster no incluye un lenguaje, lo dice el servidor; la licencia básica de Elasticsearch trae SQL y ES|QL.
Elasticsearch
Traducir a Query DSL, en SQL, le pide a Elasticsearch el Query DSL equivalente (_sql/translate) y lo abre en Query DSL, con el índice del FROM ya puesto.
OpenSearch
OpenSearch no traduce SQL a Query DSL: sólo da el plan de su motor. Por eso, con OpenSearch, la barra no trae Traducir a Query DSL.
Sólo lee
La Consulta no escribe: el cuerpo de Query DSL va siempre a _search, SQL, ES|QL y PPL sólo consultan, y un DELETE escrito en SQL no se envía. No hay aquí borrado ni actualización por consulta (_delete_by_query, _update_by_query).
Qué enseña cada pestaña de un índice, qué se puede escribir y cómo, adónde va el registro de lentas y por qué no hay reindexado.
Dónde está: Espacio de Trabajo › Herramientas › Índices
Aplica a:ElasticsearchOpenSearch
La pestaña tiene tres secciones, en el selector de la barra: Índices, Plantillas y Pipelines. Recargar vuelve a leer la que se ve.
Índices
A la izquierda, los índices del clúster con su salud —un glifo y su nombre, nunca sólo un color—, sus documentos y su tamaño. Los de sistema (los que empiezan por punto y los que el servidor oculta) van plegados en su grupo. La cifra de documentos de la lista es la de Lucene, que cuenta aparte cada objeto de un campo nested; los que devuelve una búsqueda están en Estadísticas. Elige un índice y a la derecha sale su detalle, en pestañas que se leen al abrirlas:
- Campos: el mapping como árbol, cada campo con su tipo, sus parámetros y sus subcampos.
- Ajustes: los ajustes escritos en el índice (no los de omisión), con el umbral de lentas delante.
- Shards: cada shard, primario o réplica, con su estado, su nodo y, si no tiene nodo, el motivo.
- Alias: los alias que apuntan al índice.
- Documentos: una muestra de los documentos, de 25 en 25.
- Estadísticas: los documentos de primer nivel junto a los de Lucene, el tamaño y los contadores de actividad, que suman desde que el índice se abrió en su nodo.
Los documentos
La muestra va en el orden en que el índice los guarda y dice el total exacto. Sólo recorre los primeros 10 000 (index.max_result_window): más allá la pantalla lo dice, y para recorrer un índice entero está la Consulta, que pagina con search_after.
Lo que se escribe Nuevo índice…, en la barra, abre el JSON de un índice nuevo, con un shard, sin réplicas y el mapping vacío. Borrar índice…, en el detalle, pregunta nombrando el índice y cuántos documentos tiene; en uno de sistema no aparece. En Documentos, Nuevo documento… crea un documento con el _id que escribas —si ya existe, el servidor lo rechaza y no lo sustituye— o con uno del servidor si lo dejas vacío. Editar documento… sustituye el documento entero: un campo que quites en la hoja desaparece. Y sólo si nadie lo cambió desde que lo leíste; si no, el servidor lo rechaza y no pisa el cambio del otro. Borrar documento… pregunta nombrando su _id. Todo pasa por la protección de la conexión, y con la etiqueta de solo lectura nada de esto aparece.
El registro de lentas Editar umbral de lentas…, en Ajustes, fija a partir de cuánto se escribe una búsqueda lenta en el registro: la fase de consulta y la de recuperación, cada una en aviso e info. Se escribe un tiempo con su unidad (500ms, 2s); -1 lo apaga, y vacío vuelve al de omisión, que no registra nada.
OpenSearch
En OpenSearch la hoja trae además el nivel del registro (index.search.slowlog.level).
El registro no lo guarda Calíope: lo escribe el servidor. En una instalación de paquete va a su directorio de registros (path.logs), a un archivo <clúster>_index_search_slowlog; en un contenedor, a la salida del contenedor (docker logs).
Plantillas y Pipelines
Son del clúster, no de un índice, y sólo se leen. Cada fila resume la plantilla (sus patrones, su prioridad y de qué plantillas se compone) o el pipeline (su descripción y cuántos procesadores tiene); ábrela para ver su JSON entero. Las plantillas antiguas (_template) también salen, marcadas como tales. Las que el servidor declara suyas y las que empiezan por punto van plegadas en su grupo. Calíope no las edita: se cambian por la API.
Lo que no hace
No hay reindexado (_reindex) ni cambio de tipo de un campo existente: el servidor no cambia el tipo de un campo que ya tiene datos, y copiar un índice en otro es un trabajo largo del servidor que se lanza por la API.
Qué quieren decir verde, amarillo y rojo, cómo se cuentan los nodos, qué son los papeles y cómo leer por qué un shard no tiene nodo.
Dónde está: Espacio de Trabajo › Herramientas › Clúster
Aplica a:ElasticsearchOpenSearch
La pestaña lee el clúster al abrirla y con Actualizar; no se refresca sola, porque el clúster no avisa de sus cambios.
La salud
Arriba va la salud con su glifo y su nombre, nunca sólo un color:
- green: todos los shards, primarios y réplicas, tienen nodo.
- yellow: todos los primarios tienen nodo, pero alguna réplica no. Los datos se leen y se escriben enteros; lo que falta es la copia que daría la réplica si un nodo cayera.
- red: algún primario no tiene nodo, y los documentos de ese shard no se pueden leer ni escribir.
Debajo, cuántos nodos responden de los que el clúster espera. La cuenta sale de los nodos que la sesión ha visto y de la configuración de votación del clúster, así que un nodo que cayó antes de conectar también se cuenta: se nombra por su identificador, porque su nombre no lo dice nadie. Luego el master (_cat/master) y los shards: activos, relocalizando, inicializando y sin asignar. Al caer un nodo, sus réplicas esperan un minuto a que vuelva (index.unassigned.node_left.delayed_timeout) antes de copiarse en otro, y la cifra lo dice entre paréntesis.
Nodos
Una fila por nodo con sus papeles, heap, RAM, CPU, carga, disco, shards y versión. En Papeles van las letras de node.role: m master, d datos, i ingesta, r cliente remoto; las demás son niveles de datos. Con el puntero encima se leen enteras.
Shards con problemas
Los shards que no están activos: primero los sin asignar, los primarios antes que las réplicas y los índices del usuario antes que los de sistema. El primero sin asignar se explica con POST /_cluster/allocation/explain: Motivo (por ejemplo NODE_LEFT, el nodo se fue), ¿Se puede asignar? y lo que decide cada nodo. Explicación del servidor es el texto del servidor tal cual, en inglés. Un caso frecuente: con dos nodos, un índice de dos réplicas no tiene sitio para la segunda, porque un nodo no guarda dos copias del mismo shard (same_shard), y el clúster sigue en amarillo hasta que vuelva el tercero.
Tareas del clúster en cola y Recuperaciones en curso
Las tareas del clúster que esperan turno (_cat/pending_tasks) y las copias de shards que están en marcha (_cat/recovery).
Si una parte no se pudo leer, lleva su aviso y las demás se enseñan igual. La pestaña sólo lee: no reasigna shards ni cambia ajustes del clúster.
Qué mide cada tarjeta, por qué el aviso del heap sale al 75 %, por qué las tasas son diferencias entre dos lecturas y qué quiere decir un rechazo en un thread pool.
Dónde está: Espacio de Trabajo › Herramientas › Nodo
Aplica a:ElasticsearchOpenSearch
La pestaña lee el nodo al abrirla y, mientras está delante, cada 5 s; al cambiar de pestaña deja de leer. Mientras se lee sola, Actividad lo enseña como «Nodo de búsqueda, cada 5 s». Actualizar lo lee en el momento.
Nodo
Por omisión es el nodo que contesta a la sesión. Si el clúster tiene más de uno, el selector deja elegir otro.
Las tarjetas
- Heap de la JVM: lo ocupado sobre el máximo. Desde el 75 % lleva aviso con glifo y texto: es el umbral en el que Elastic aconseja investigar la presión de memoria, porque por encima la JVM pasa más tiempo recolectando y los circuit breakers, que cortan una petición antes de que el nodo se quede sin memoria, están más cerca de saltar.
- Recolecciones de basura: las de la generación joven y las de la vieja, con el tiempo que llevan; que las viejas crezcan deprisa es la señal de un heap que no da abasto.
- CPU: la de la máquina y, debajo, la del proceso del nodo.
- Disco: lo ocupado es el total menos lo disponible. Desde el 85 % lleva aviso: es el umbral bajo de disco del clúster (cluster.routing.allocation.disk.watermark.low), y por encima el clúster deja de asignar réplicas a ese nodo.
- Consultas por segundo y Documentos indexados por segundo: la primera, con la latencia media de las consultas del intervalo.
Las tasas son diferencias
El servidor sólo da contadores acumulados desde que arrancó el nodo. Una tasa es la diferencia entre dos lecturas dividida por el tiempo que pasó entre ellas según el reloj del nodo, así que la primera lectura dice «Hace falta una segunda lectura» y la cifra llega con la siguiente. Debajo va el total desde el arranque.
Thread pools
Cada pool con sus hilos, los activos, la cola, los rechazados y los completados. Cuando la cola de un pool se llena, el nodo rechaza la petición siguiente con un 429 en vez de esperar. Los pools con rechazos se destacan con un glifo, y los que no tienen actividad van plegados. Rechazos y completados se cuentan desde el arranque: una cifra alta puede ser antigua, y lo que importa es si crece entre lecturas.
Ficha del nodo
La versión, los papeles, la dirección, el sistema operativo, los procesadores, la JVM, el heap máximo, las rutas y los plugins.
Hilos calientes
Con Leer hilos calientes el nodo muestrea medio segundo y devuelve los tres hilos que más CPU gastaron. Es el texto del servidor tal cual, en inglés; con el nodo quieto sólo trae la cabecera.
La pestaña sólo lee: no cambia ajustes del nodo.
Palabras clave: elasticsearch, opensearch, nodo, jvm, heap, gc, recolección de basura, cpu, disco, watermark, consultas por segundo, indexación, thread pool, rechazos, rejected, 429, hilos calientes, hot threads, plugins
Tareas: lo que corre en el clúster y cómo cancelarlo
Qué enseña el árbol de tareas, cada cuánto se relee, qué tareas se pueden cancelar y qué contesta el servidor al cancelar.
Dónde está: Espacio de Trabajo › Herramientas › Tareas
Aplica a:ElasticsearchOpenSearch
La pestaña lee las tareas del clúster (GET /_tasks?detailed=true&group_by=parents) al abrirla y, mientras está delante, cada 3 s; al cambiar de pestaña deja de leer. Mientras se lee sola, Actividad lo enseña como «Tareas de búsqueda, cada 3 s». Actualizar las lee en el momento.
El árbol
Cada tarea madre lleva debajo sus hijas, ordenadas por lo que llevan corriendo. Cada fila dice la acción, la descripción, el nodo por su nombre (si no se sabe, su identificador) y cuánto lleva. En un delete by query, un update by query o un reindex dice además cuántos documentos lleva de cuántos.
El filtro
Casa con la acción o la descripción, sin distinguir mayúsculas, y una madre se queda si casa alguna de sus hijas.
Lo que no se ofrece para cancelar
- Pedir la lista también es una tarea del servidor: sale marcada «esta lista».
- Las persistentes («persistente, del clúster») las marca cancelables el servidor, pero son del propio clúster y no se ofrecen.
- Las que el servidor no marca cancelables, las que ya tienen la cancelación pedida y, en una conexión de solo lectura, todas.
Cancelar tarea
Antes se confirma: la alerta nombra la acción, la descripción y el nodo, y Dejarla correr la deja seguir. Cancelar pide al servidor que la detenga en cuanto pueda; lo que ya hizo no se deshace. El servidor contesta siempre con éxito y la pantalla dice lo que pasó: que la marcó cancelada, que la tarea ya había terminado o que su nodo ya no está en el clúster.
Qué enseña la pestaña de un repositorio y de sus instantáneas, cómo se crea una, cómo se sigue hasta que acaba y cómo se restaura a mano.
Dónde está: Espacio de Trabajo › Herramientas › Instantáneas
Aplica a:ElasticsearchOpenSearch
La pestaña lee los repositorios de instantáneas del servidor (GET /_snapshot) y, del elegido, sus instantáneas (GET /_snapshot/<repositorio>/_all).
Repositorio
Si el servidor tiene más de uno, se elige en la barra. Debajo van su tipo y sus ajustes; un ajuste que nombra una credencial sale tapado (••••). Sin ningún repositorio, la pantalla lo dice: un repositorio se registra en el servidor (PUT /_snapshot/<nombre>), y uno de tipo fs necesita que su carpeta esté en path.repo de cada nodo, en la configuración del servidor. Calíope no registra repositorios.
Las instantáneas
Van de la más reciente a la más antigua. Cada una dice su estado con glifo y palabras («Completa», «En curso», «Parcial: algún shard falló», «Fallida»), cuándo empezó, cuánto duró, sus shards y sus índices, y el fallo de cada shard que falló.
Crear instantánea
Abre una hoja con el nombre y los índices. El nombre propuesto lleva la fecha y la hora (snapshot-AAAA.MM.DD-HHMMSS); va en minúsculas y sin espacios, o el servidor lo rechaza y la hoja enseña su motivo. Los índices van separados por comas y admiten comodines; vacío son todos los del clúster. Un índice que no existe se salta, y el estado global (plantillas y ajustes del clúster) no entra. Crear pasa por el guarda de escritura de la conexión: en una de solo lectura el botón no aparece.
La hoja se cierra en cuanto el servidor acepta la petición, y Actividad sigue la instantánea como «Instantánea de búsqueda», con los shards hechos como avance. No tiene «Detener»: parar sería dejarla a medias. El final lo confirma la lista de instantáneas, porque OpenSearch tarda un instante en darla por terminada. Si a los diez minutos sigue en curso, la pantalla lo dice y Actualizar enseña después cómo acabó.
Restaurar no se ofrece
Restaurar sobrescribe índices abiertos y se decide fuera de una herramienta de consulta. El pie de la lista lo dice y escribe la petición para hacerlo a mano: POST /_snapshot/<repositorio>/<nombre>/_restore.