Lenguaje de consultas (LQL)

Para qué sirve#

LQL es el lenguaje con el que le hacés preguntas a tus datos en Explorar, en los tiles de Dashboards y donde se pida una consulta. Es uno solo para todos los tipos de dato: no hace falta aprender uno distinto para métricas, logs, eventos o trazas.

Escribir consultas a mano es para Sistemas y Administración. El resto de los roles puede armarlas con el asistente "Armar con ayuda", que genera el texto por vos.

Una consulta siempre solo lee: no modifica ni borra datos.

Cuándo usarlo#

• El asistente no llega a lo que necesitás (por ejemplo, calcular un porcentaje entre dos conteos).
• Querés guardar y repetir una pregunta exacta en un tile.
• Querés ajustar la consulta que armó el asistente.

Cómo se escribe, paso a paso#

1. Empezá por el origen: from logs, from eventos, from trazas, from rum o series (métricas).
2. Agregá cláusulas, una detrás de otra, cada una con su palabra clave: where, show, order by, take, etc. No hay barras |.
3. Si querés agrupar o calcular, usá una función de resumen, como count, sum(monto) o p95(duracion), con by y every.
4. Ejecutá con Ctrl+Enter. Si hay un error, el editor lo marca con línea y columna y sugiere el nombre correcto.

Los saltos de línea y los espacios dan igual. Los comentarios empiezan con #.

Ejemplos para copiar#

# Métricas: series de tiempo
series avg(cpu) by host
series p95(duracion) where servicio = "web-turnos"
series sum(pedidos) by servicio, operacion every 5m
series rate(errores) / rate(pedidos) * 100 by servicio        # % de errores

# Logs
from logs
where servicio = "web-turnos" and nivel = "ERROR"
where mensaje has "timeout"
show ts, servicio, nivel, mensaje
order by ts desc
take 100

from logs where nivel in ("ERROR", "WARN") count by servicio every 10m

# Eventos de negocio
from eventos where evento = "pago.aprobado" sum(monto) by canal
from eventos where evento startswith "turno." count by evento every 1h
from eventos where evento = "pago.rechazado" show ts, monto, canal take 50

# Experiencia de usuarios
from rum where evento = "rum.vital" and vital = "LCP" p75(valor) by vista

# Trazas
from trazas where servicio = "web-turnos" and duracion > 1s order by duracion desc take 20
from trazas where error = true count by servicio, operacion

# Más
from logs where servicio = "web-turnos" extract "turno {turno:int} reservado" from mensaje where turno is not null take 20
from logs exclude nivel = "DEBUG" series count by nivel every 5m
from eventos compute hora = hour(ts) count by hora
from eventos where evento = "pago.aprobado" compute tramo = if(monto > 50000, "alto", "normal") count, sum(monto) by tramo
from trazas where error = true unique operacion show ts, servicio, operacion, duracion
from eventos count_if(evento = "pago.rechazado") * 100 / count_if(evento startswith "pago.") every 1h
from eventos total = sum(monto), cantidad = count by canal order by total desc
from logs hide bucket, span_id rename mensaje as texto

Orígenes y campos#

Cada origen tiene sus campos. En el editor, el autocompletado te muestra los reales de tu instalación, con valores sugeridos.

Notas:

• En rum, sitio se escribe con el nombre de la aplicación como figura en Experiencia de usuarios (sitio = "Demo web"). Si dos aplicaciones tienen el mismo nombre en distintas plataformas, usá "Web · Demo web". plataforma es Web, Android o iOS.
• Los atributos con punto se escriben así: attrs["pago.medio"].
• Una métrica es un número medido cada cierto tiempo (por ejemplo, el uso de CPU). Un evento es un hecho puntual.

Cláusulas#

Operadores#

Las palabras clave van en minúscula. Palabras reservadas que no sirven como nombre de campo: from series where exclude show hide compute rename order by take extract unique every as and or not in has startswith endswith matches is null asc desc true false last since until today yesterday. Si un campo se llama así, escribilo entre acentos graves: `order`.

Agregaciones#

Podés ponerles nombre (total = sum(monto)) y combinarlas con aritmética (count_if(...) * 100 / count). En métricas, los percentiles solo valen para histogramas y medidores, y también existe rate(x) (ritmo por segundo).

every 5m agrupa en tramos de tiempo. Si lo omitís, se calcula para tener unos 60 puntos del período.

Funciones para calcular#

Extraer datos de un texto#

extract "patrón" from campo saca partes de un texto como columnas nuevas. En el patrón, {nombre} toma el texto hasta el próximo literal; también {nombre:int} (entero), {nombre:num} (número), {nombre:ip} y {nombre:palabra}. El * ignora un tramo. Hasta 10 marcadores por patrón.

Período dentro de la consulta#

Una cláusula opcional, a lo sumo una por consulta:

• Las fechas sin zona horaria se interpretan en la zona horaria de tu organización. Con zona (Z o -03:00) se respeta la escrita.
• Si la consulta trae período, ese manda sobre el del dashboard, el tile o Explorar. El selector queda deshabilitado con el cartel "Período de la consulta".
• last(x) con paréntesis es la agregación "último valor"; last 2h sin paréntesis es el período.

Topes y límites#

Para evitar cortes, filtrá temprano con where, achicá el período y limitá con take.

Seguridad#

Los valores que escribís nunca se pegan sin control en la consulta real: Lymen valida todo contra el catálogo de campos y los escapa. Cada consulta ejecutada queda en una auditoría.

Consultas en formato anterior#

Si pegás una consulta del formato anterior, el editor la detecta y ofrece Convertir. Los tiles viejos se pasan solos al formato nuevo cuando es posible; los que no, se ven en solo lectura con el cartel "Consulta avanzada anterior".

Problemas comunes#

• "escribí «where» en minúscula": las palabras clave van en minúscula.
• Usé == y falla: es un solo =.
• "el campo «servcio» no existe": revisá el nombre; el editor sugiere el correcto.
• Con matches da error: regex muy larga (más de 200 caracteres) o con referencias hacia atrás.
• "El número de percentile tiene que ser un entero de 1 a 99": escribilo tal cual, por ejemplo percentile(duracion, 80).
• "el período no puede pasar de 31 días": acortalo.
• Un campo con nombre reservado: ponelo entre acentos graves.
• No me deja escribir: tu rol es de consulta; usá el asistente.