Centralizando los registros de la API de calificación de OpenClaw con Grafana Loki

1. Introducción

OpenClaw es una solución de gestión de vulnerabilidades que genera gran cantidad de datos de registro (logs) críticos para la seguridad y el rendimiento. Sin una estrategia de registro de logs centralizado, los equipos de desarrollo y operaciones pueden perder visibilidad, lo que dificulta la detección de incidentes y la depuración.

Grafana Loki, combinado con la potencia visual de Grafana, ofrece una alternativa ligera a los sistemas tradicionales de agregación de logs. En esta guía, descubrirás cómo:

• Instalar y configurar Loki para recibir logs de OpenClaw.
• Adaptar ejemplos de código a español, con variables y comentarios claros.
• Integrar la solución dentro del ecosistema UBOS para aprovechar sus capacidades de automatización.

Todo el proceso está pensado para desarrolladores hispanohablantes que buscan una solución de monitoreo robusta y fácil de mantener.

2. Configuración de Grafana Loki

2.1. Despliegue rápido con Docker

El método más sencillo para iniciar Loki es mediante Docker. Ejecuta el siguiente comando en tu terminal:

docker run -d \
  --name=loki \
  -p 3100:3100 \
  -v $(pwd)/loki-config.yml:/etc/loki/local-config.yml \
  grafana/loki:2.9.1 -config.file=/etc/loki/local-config.yml

2.2. Archivo de configuración básico (loki-config.yml)

Guarda este contenido como loki-config.yml en el mismo directorio donde ejecutas Docker:

auth_enabled: false

server:
  http_listen_port: 3100

ingester:
  lifecycler:
    address: 127.0.0.1
    ring:
      kvstore:
        store: inmemory
      replication_factor: 1
  chunk_idle_period: 5m
  max_chunk_age: 1h

schema_config:
  configs:
    - from: 2020-10-24
      store: boltdb-shipper
      object_store: filesystem
      schema: v11
      index:
        prefix: index_
        period: 24h

storage_config:
  boltdb_shipper:
    active_index_directory: /tmp/loki/index
    cache_location: /tmp/loki/cache
    shared_store: filesystem
  filesystem:
    directory: /tmp/loki/chunks

limits_config:
  enforce_metric_name: false
  reject_old_samples: true
  reject_old_samples_max_age: 168h

2.3. Conectar Grafana a Loki

Una vez Loki está corriendo, abre Grafana (puedes usar la imagen oficial grafana/grafana) y añade una nueva fuente de datos:

1. Ir a Configuration > Data Sources.
2. Seleccionar Loki y establecer la URL como http://localhost:3100.
3. Guardar y probar la conexión.

Con la fuente de datos lista, ya puedes crear paneles que consulten los logs de OpenClaw usando etiquetas como app=openclaw o nivel=error.

3. Adaptación de ejemplos de código en español

A continuación, se muestra cómo enviar logs desde la API de OpenClaw a Loki usando Python. El código está totalmente comentado en español y utiliza nombres de variables descriptivos.

import json
import requests
import datetime

# URL del endpoint HTTP de Loki
URL_LOKI = "http://localhost:3100/loki/api/v1/push"

def crear_entrada_log(mensaje: str, nivel: str = "info"):
    """
    Construye una entrada de log compatible con Loki.
    :param mensaje: Texto del mensaje a registrar.
    :param nivel: Nivel de severidad (info, warning, error).
    :return: Diccionario listo para enviar.
    """
    timestamp = int(datetime.datetime.utcnow().timestamp() * 1e9)  # nanosegundos
    return {
        "streams": [
            {
                "stream": {
                    "app": "openclaw",
                    "nivel": nivel
                },
                "values": [
                    [str(timestamp), mensaje]
                ]
            }
        ]
    }

def enviar_a_loki(payload: dict):
    """
    Envía el payload a Loki mediante una petición POST.
    """
    headers = {"Content-Type": "application/json"}
    respuesta = requests.post(URL_LOKI, data=json.dumps(payload), headers=headers)
    if respuesta.status_code != 204:
        print(f"Error al enviar log: {respuesta.status_code} - {respuesta.text}")

# Ejemplo de uso
if __name__ == "__main__":
    log = crear_entrada_log("Inicio de escaneo de vulnerabilidades", "info")
    enviar_a_loki(log)

Este fragmento se puede integrar directamente en cualquier módulo de la API de OpenClaw que necesite registrar eventos críticos.

3.1. Uso de la biblioteca loguru para simplificar

Si prefieres una solución más elegante, la biblioteca loguru permite crear un handler personalizado que envíe los logs a Loki automáticamente.

from loguru import logger
import requests
import json
import datetime

class LokiHandler:
    def __init__(self, url):
        self.url = url

    def write(self, message):
        # Extraer nivel y texto del mensaje de Loguru
        nivel = message.record["level"].name.lower()
        texto = message.record["message"]
        payload = {
            "streams": [
                {
                    "stream": {"app": "openclaw", "nivel": nivel},
                    "values": [[str(int(datetime.datetime.utcnow().timestamp()*1e9)), texto]]
                }
            ]
        }
        requests.post(self.url, data=json.dumps(payload), headers={"Content-Type": "application/json"})

# Configurar Loguru
logger.remove()  # Eliminar el handler por defecto
logger.add(LokiHandler("http://localhost:3100/loki/api/v1/push"), level="INFO")

# Registro de ejemplo
logger.info("Escaneo completado sin errores")
logger.error("Fallo al conectar con la base de datos")

Con este enfoque, cualquier llamada a logger.info() o logger.error() se enviará automáticamente a Loki.

4. Integración con OpenClaw

OpenClaw expone su API mediante FastAPI. A continuación, se muestra cómo conectar la API con el cliente de logs que hemos creado.

from fastapi import FastAPI, Request
from loguru import logger

app = FastAPI()

# Inyectar el handler de Loki al iniciar la aplicación
logger.remove()
logger.add(LokiHandler("http://localhost:3100/loki/api/v1/push"), level="INFO")

@app.post("/escaneo")
async def iniciar_escaneo(request: Request):
    datos = await request.json()
    logger.info(f"Solicitud de escaneo recibida: {datos}")
    # Lógica de escaneo (simulada)
    resultado = {"estado": "en_progreso", "objetivo": datos.get("objetivo")}
    logger.info(f"Escaneo iniciado para {resultado['objetivo']}")
    return resultado

@app.get("/estado/{id_escaneo}")
async def obtener_estado(id_escaneo: str):
    logger.info(f"Consulta de estado para escaneo {id_escaneo}")
    # Simulación de respuesta
    return {"id": id_escaneo, "estado": "completado"}

Al ejecutar la aplicación, cada petición HTTP quedará registrada en Loki con la etiqueta app=openclaw, lo que permite filtrarlas fácilmente en Grafana.

4.1. Despliegue en la nube con UBOS

UBOS simplifica el despliegue de aplicaciones SaaS mediante su plataforma. Puedes crear un proyecto, añadir el Web app editor on UBOS y subir tu contenedor Docker con Loki y la API de OpenClaw en pocos clics.

Para una solución completa, combina:

• Host OpenClaw en UBOS – infraestructura gestionada.
• Workflow automation studio – automatiza la recolección de logs.
• Enterprise AI platform by UBOS – añade análisis de IA a los logs.

Con esta arquitectura, los equipos de seguridad pueden crear alertas automáticas basadas en patrones de logs, gracias a la integración de IA de UBOS.

5. Conclusión y llamado a la acción

Centralizar los logs de la API de OpenClaw con Grafana Loki brinda:

• Visibilidad en tiempo real de eventos críticos.
• Búsqueda rápida mediante etiquetas, sin necesidad de indexar todo el contenido.
• Escalabilidad horizontal y bajo costo operativo.
• Integración nativa con la UBOS platform para automatizar flujos y aplicar IA.

Si deseas acelerar tu proceso de monitoreo y aprovechar la potencia de la IA, te invitamos a probar la solución completa en UBOS:

¿Tienes preguntas o necesitas asistencia personalizada? Visita la sección About UBOS y ponte en contacto con nuestro equipo de expertos.

Referencias

Para profundizar en la arquitectura de Loki y casos de uso avanzados, consulta el artículo original de Centralized Logging with Loki & Grafana en Medium.

Plantillas UBOS relacionadas

Explora plantillas que pueden complementar tu stack de monitoreo:

• AI SEO Analyzer
• AI Article Copywriter
• AI Video Generator