Registro centralizado: Parte 5 — Loki y Grafana

Loki — un sistema de almacenamiento de registros de Grafana Labs. Su principal diferencia con ELK, OpenSearch y Graylog es que Loki no construye un índice de texto completo. Solo se indexan las etiquetas (labels): un conjunto corto de pares “clave — valor” que describen la fuente: servidor, servicio, entorno. Las propias líneas de registros se almacenan en bloques comprimidos, incluso en un almacenamiento compatible con S3. Gracias a esto Loki requiere notablemente menos recursos, y los registros se visualizan en Grafana junto con las métricas de Prometheus.

Licencia

Desde abril de 2021 Loki, al igual que Grafana, se distribuye bajo AGPLv3 — una licencia abierta aprobada por OSI. Los agentes y varias librerías quedaron bajo Apache 2.0. Para una empresa que ejecuta Loki para sus propios registros, AGPLv3 no impone restricciones; la condición sobre la divulgación de cambios aplica a quienes modifican Loki y lo ofrecen como servicio de red.

Componentes

• Loki — recibe, almacena y entrega registros. Para instalaciones pequeñas se ejecuta como un solo proceso; para instalaciones grandes — como un conjunto de servicios separados.
• Grafana — interfaz para búsqueda (sección Explore), dashboards y alertas.
• Agente en los servidores — lee registros, añade etiquetas y las envía a Loki. Actualmente es Grafana Alloy.

Promtail ya no se mantiene

Durante mucho tiempo el agente para Loki fue Promtail, y la mayoría de las instrucciones antiguas describen precisamente ese agente. Desde el 13 de febrero de 2025 Promtail solo recibió correcciones, y el 2 de marzo de 2026 su soporte finalizó por completo. Grafana recomienda migrar a Grafana Alloy. Para convertir la configuración existente hay un comando:

alloy convert --source-format=promtail --output=config.alloy promtail.yaml

Convierte la configuración de Promtail al formato Alloy; el resultado debe verificarse manualmente.

Ejemplo de configuración de Alloy

La configuración de Alloy consiste en componentes conectados entre sí. Para leer archivos de /var/log y enviarlos a Loki se necesitan tres componentes: búsqueda de archivos, lectura y envío.

local.file_match "system" {
  path_targets = [{
    __address__ = "localhost",
    __path__    = "/var/log/*.log",
    job         = "system",
  }]
}

loki.source.file "system" {
  targets    = local.file_match.system.targets
  forward_to = [loki.write.default.receiver]
}

loki.write "default" {
  endpoint {
    url = "http://loki.internal:3100/loki/api/v1/push"
  }
  external_labels = {
    host = "web-01",
    env  = "prod",
  }
}

local.file_match encuentra archivos por patrón, loki.source.file los lee y transmite las líneas, y loki.write las envía a Loki y añade a cada entrada las etiquetas host y env. Para el journal del sistema existe el componente loki.source.journal, y para contenedores — loki.source.docker.

Etiquetas y cardinalidad

Las etiquetas son la parte más importante de la configuración de Loki. Cada combinación única de valores de etiquetas forma un flujo (stream) separado, y para cada flujo se almacenan su propio índice y sus propios bloques de datos. La documentación de Loki indica claramente que el sistema está pensado para flujos de larga vida y un número reducido de valores de etiqueta.

Buenas etiquetas — con un conjunto pequeño y estable de valores: env, cluster, namespace, app, job, host.

Malas etiquetas — con un número ilimitado de valores: identificadores de petición, de trazas, usuarios y pedidos, direcciones IP, timestamps. Incluso el nivel de registro y el código de respuesta HTTP la documentación aconseja no ponerlos como etiquetas, sino buscarlos con un filtro de texto. Una alta cardinalidad conduce a un índice enorme y a miles de bloques pequeños en el almacenamiento, y Loki empieza a funcionar de forma lenta.

Para campos que se buscan con frecuencia pero tienen muchos valores, por ejemplo el identificador de cliente, en Loki existen metadatos estructurados: se almacenan junto con la entrada y no entran en el índice.

LogQL

Las consultas se escriben en LogQL. Una consulta empieza con la selección de flujos por etiquetas, y luego sigue una cadena de filtros y procesadores.

Líneas con errores en los registros de nginx en servidores de producción:

{job="nginx", env="prod"} |= "error"

Parseo de JSON y filtrado por campo:

{app="payments"} | json | level="error" | order_id != ""

Número de errores por segundo por servidor en ventanas de cinco minutos — esta consulta se puede mostrar en un gráfico y usar en una alerta:

sum by (host) (rate({job="nginx"} |= " 500 " [5m]))

La sintaxis es similar a PromQL, por lo que a quienes trabajan con Prometheus les resulta más fácil aprenderla.

Ventajas

• Ahorro de recursos. El índice por etiquetas es muchas veces más pequeño que el de texto completo; las líneas se almacenan comprimidas, incluso en un económico almacenamiento de objetos.
• Registros junto a las métricas. En Grafana se puede saltar del gráfico de una métrica a los registros del mismo servicio en el mismo intervalo.
• Inicio sencillo. Para una infraestructura pequeña basta con un proceso Loki y un agente en los servidores.
• Licencia abierta AGPLv3.

Limitaciones

• La búsqueda por contenido es más lenta. Sin índice de texto completo la consulta por texto recorre las líneas de los flujos seleccionados. Cuanto más precisa sea la selección de etiquetas y más corto el intervalo, más rápida será la consulta.
• El procesamiento es más modesto que en Logstash o las canalizaciones de Graylog: el trabajo principal de parsing lo realizan el agente y las consultas LogQL.
• Disciplina con las etiquetas. Una etiqueta inadecuada con un gran número de valores puede sobrecargar el sistema.

Errores típicos

• Nueva instalación basada en Promtail. El agente no está soportado; para servidores nuevos use Alloy desde el principio.
• Identificador de petición o dirección IP como etiqueta. El número de flujos crece en avalancha.
• Sin periodo de retención. En Loki se define con el parámetro retention_period y se activa en el compactador; sin esto los datos se almacenan indefinidamente.
• Loki expuesto al exterior sin autenticación. En el modo de un solo usuario Loki por sí mismo no verifica quién envía o lee los registros. El acceso se restringe mediante un firewall o un proxy inverso con autenticación.

Cuándo elegir Loki

Loki es adecuado si Prometheus ya recoge las métricas, los dashboards se construyen en Grafana, y se quiere añadir registros a bajo coste. Funciona bien en Kubernetes y con un gran volumen de registros en los que la búsqueda se realiza principalmente por fuente y tiempo. Si se necesita búsqueda de texto completo y análisis complejo del contenido, OpenSearch o ELK son más adecuados.