Saltar al contenido principal

OpenObserve

Guía completa para configurar y usar OpenObserve en Floutic para observabilidad completa de la aplicación.

¿Qué es OpenObserve?​

OpenObserve es una plataforma de observabilidad open-source que reemplaza a Elasticsearch, Logstash, Kibana, Prometheus y Grafana. En Floutic se usa para:

  • Logs: Errores, eventos y logs estructurados
  • Métricas: Métricas de API, negocio, infraestructura y rendimiento
  • RUM (Real User Monitoring): Datos de usuarios reales desde el frontend
  • Trazas: Seguimiento de requests (futuro)

Configuración Inicial​

Paso 1: Verificar que OpenObserve esté corriendo​

# Verificar estado
docker compose ps openobserve

# Ver logs
docker compose logs openobserve | tail -20

# Verificar salud
curl http://localhost:5080/api/default/health

Paso 2: Configurar Variables de Entorno​

Backend (backend/.env):

# OpenObserve Configuration
OPENOBSERVE_URL=http://openobserve:5080  # Interno en Docker
OPENOBSERVE_USER=root@example.com
OPENOBSERVE_PASSWORD=openobserve_pass123
OPENOBSERVE_API_KEY=  # Opcional, obtener desde Settings → API Keys

# Configuración de logging
LOG_TO_OPENOBSERVE=false  # true para enviar todos los logs (no recomendado en producción)

Frontend (frontend/.env):

# OpenObserve RUM (Real User Monitoring)
VITE_OPENOBSERVE_CLIENT_TOKEN=  # Obtener desde Settings → API Keys → RUM Token
VITE_OPENOBSERVE_URL=https://oo.haorp.es  # URL pública

Paso 3: Crear los Streams​

Los streams se crean automáticamente cuando se envía el primer log, pero puedes validarlos:

Opción A: Diagnóstico completo (Recomendado)​

# Ejecutar diagnóstico completo desde Docker
docker compose exec backend python scripts/diagnose_openobserve.py

Este script verifica:

  • ✅ Conexión con OpenObserve
  • ✅ Autenticación (user/password o API key)
  • ✅ Envío de logs directo
  • ✅ Uso del módulo de observabilidad
  • ✅ Validación de streams

Opción B: Crear desde la UI​

  1. Accede a OpenObserve: https://oo.haorp.es (o http://localhost:5080 en desarrollo)
  2. Inicia sesión con las credenciales de tu .env
  3. Los streams se crearán automáticamente cuando llegue el primer log

Streams Disponibles​

Floutic utiliza los siguientes streams organizados por tipo:

Streams de Logs​

backend-stream​

Logs del backend (errores, eventos importantes).

Cuándo se envía:

  • Errores no controlados (excepciones)
  • Eventos importantes de negocio
  • Cuando LOG_TO_OPENOBSERVE=true (todos los logs)

Estructura:

{
  "type": "python_log",
  "level": "ERROR",
  "logger": "app.api.endpoints.projects",
  "message": "Error message",
  "module": "projects",
  "function": "create_project",
  "line": 123,
  "timestamp": "2025-01-21T10:00:00Z"
}

frontend-stream​

Logs del frontend (errores JavaScript, eventos).

Cuándo se envía:

  • Errores JavaScript no controlados
  • Errores de red
  • Eventos importantes del frontend

Estructura:

{
  "type": "frontend_error",
  "level": "error",
  "message": "Error message",
  "url": "/dashboard/empresa",
  "userAgent": "Mozilla/5.0...",
  "timestamp": "2025-01-21T10:00:00Z"
}

client-errors-stream​

Errores HTTP 4xx del backend.

Cuándo se envía:

  • Requests con status 400-499
  • Validaciones fallidas
  • Permisos denegados

server-errors-stream​

Errores HTTP 5xx del backend.

Cuándo se envía:

  • Requests con status 500-599
  • Errores de servidor
  • Excepciones no controladas

Streams de Métricas​

api-metrics-stream​

Métricas de rendimiento de la API.

Datos incluidos:

  • Endpoint y método HTTP
  • Status code
  • Tiempo de respuesta (ms)
  • User ID (si está autenticado)
  • Timestamp

Estructura:

{
  "type": "api_metric",
  "endpoint": "/api/projects",
  "method": "POST",
  "status_code": 201,
  "response_time_ms": 125.5,
  "user_id": 123,
  "timestamp": "2025-01-21T10:00:00Z"
}

business-metrics-stream​

Métricas de negocio.

Métricas incluidas:

  • Proyectos creados
  • Usuarios registrados
  • Pagos procesados
  • Reseñas creadas
  • Aplicaciones enviadas

Estructura:

{
  "type": "business_metric",
  "metric_name": "project_created",
  "value": 1.0,
  "metric_type": "counter",
  "tags": {
    "category": "automatización",
    "budget_range": "500-1000"
  },
  "timestamp": "2025-01-21T10:00:00Z"
}

performance-stream​

Métricas de rendimiento.

Métricas incluidas:

  • Tiempo de respuesta de queries
  • Tiempo de procesamiento
  • Uso de memoria
  • Tiempo de renderizado

infrastructure-stream​

Métricas de infraestructura.

Métricas incluidas:

  • CPU usage
  • Memoria usage
  • Disco usage
  • Conexiones de base de datos
  • Conexiones Redis

Frecuencia: Cada 5 minutos

Streams de Seguridad​

security-stream​

Eventos de seguridad.

Eventos incluidos:

  • Intentos de login fallidos
  • Rate limiting activado
  • Accesos no autorizados
  • Cambios de permisos
  • Sesiones concurrentes excedidas

Estructura:

{
  "type": "security_event",
  "event_type": "rate_limit_exceeded",
  "user_id": 123,
  "ip_address": "192.168.1.1",
  "endpoint": "/api/auth/login",
  "timestamp": "2025-01-21T10:00:00Z"
}

Streams de Integraciones​

integration-stream​

Eventos de integraciones externas.

Eventos incluidos:

  • Sincronizaciones con GoHighLevel
  • Webhooks de Stripe
  • Errores de integración
  • Sincronizaciones exitosas

Streams de Jobs​

jobs-stream​

Logs de workers y jobs en background (si se implementan).

Configuración del Frontend (RUM)​

Paso 1: Obtener Client Token​

  1. Accede a OpenObserve: https://oo.haorp.es
  2. Ve a Settings → API Keys
  3. Crea o copia el RUM Token
  4. Añádelo a frontend/.env: 
    VITE_OPENOBSERVE_CLIENT_TOKEN=tu_rum_token_aqui

Paso 2: Configurar SDK​

El SDK oficial de OpenObserve se configura automáticamente si VITE_OPENOBSERVE_CLIENT_TOKEN está presente.

Datos enviados automáticamente:

  • Page views
  • Clicks e interacciones
  • Errores JavaScript
  • Métricas de rendimiento (LCP, CLS, INP)
  • Errores de red

Paso 3: Verificar​

  1. Reconstruir el frontend:

    docker compose restart frontend

  2. Abrir la aplicación en el navegador

  3. Abrir la consola (F12)

  4. Verificar mensajes:

    [OpenObserve SDK] ✅ SDK inicializado correctamente
    [OpenObserve SDK] 📊 Datos RUM se enviarán a: https://oo.haorp.es

Uso en el Código​

Backend: Enviar Logs​

from app.core.observability import send_log, get_stream

# Enviar log simple
await send_log(
    {
        "type": "custom_event",
        "message": "Evento importante",
        "user_id": current_user.id
    },
    get_stream("backend")
)

Backend: Enviar Métricas​

from app.core.metrics import send_api_metric, send_business_metric

# Métrica de API
await send_api_metric(
    endpoint="/api/projects",
    method="POST",
    status_code=201,
    response_time_ms=125.5,
    user_id=current_user.id
)

# Métrica de negocio
await send_business_metric(
    metric_name="project_created",
    value=1.0,
    metric_type="counter",
    tags={"category": "automatización"}
)

Backend: Enviar Eventos de Seguridad​

from app.core.observability import send_log, get_stream

await send_log(
    {
        "type": "security_event",
        "event_type": "rate_limit_exceeded",
        "user_id": user_id,
        "ip_address": request.client.host,
        "endpoint": str(request.url)
    },
    get_stream("security")
)

Frontend: Enviar Eventos Personalizados​

// El SDK se inicializa automáticamente
// Para enviar eventos personalizados:

import { zo } from '@openobserve/browser-rum';

zo.addAction('custom_event', {
  category: 'user_action',
  name: 'button_click',
  custom_data: {
    button_id: 'create_project',
    page: '/dashboard/empresa'
  }
});

Dashboards Recomendados​

Dashboard de API​

Métricas principales:

  • Requests por minuto
  • Tiempo de respuesta promedio (p50, p95, p99)
  • Distribución de status codes
  • Endpoints más lentos
  • Errores por endpoint

Queries útiles:

-- Requests por minuto
SELECT count(*) FROM "api-metrics-stream"
WHERE timestamp > now() - 1h
GROUP BY timestamp/1m

-- Tiempo de respuesta p95
SELECT percentile(response_time_ms, 95) FROM "api-metrics-stream"
WHERE timestamp > now() - 1h

Dashboard de Negocio​

Métricas principales:

  • Proyectos creados (por día/semana)
  • Usuarios registrados
  • Pagos procesados
  • Reseñas creadas
  • Tasa de conversión

Dashboard de Seguridad​

Métricas principales:

  • Intentos de login fallidos
  • Rate limiting activado
  • Accesos no autorizados
  • Sesiones concurrentes

Dashboard de Infraestructura​

Métricas principales:

  • CPU usage
  • Memoria usage
  • Disco usage
  • Conexiones de base de datos
  • Conexiones Redis

Alertas Recomendadas​

Alertas Críticas​

  1. Tasa de Errores de Servidor Alta

    • Condición: > 5% de requests con código 5xx en últimos 5 minutos
    • Acción: Notificar inmediatamente

  2. Tiempo de Respuesta Muy Alto

    • Condición: p95 > 2000ms en últimos 5 minutos
    • Acción: Investigar endpoints lentos

  3. Sistema de Logging Fallando

    • Condición: Tasa de éxito < 80% en últimos 5 minutos
    • Acción: Verificar conexión con OpenObserve

Alertas de Advertencia​

  1. Tasa de Errores de Cliente Alta

    • Condición: > 10% de requests con código 4xx en últimos 10 minutos

  2. Uso de Recursos Alto

    • Condición: CPU > 80% o Memoria > 90% en últimos 5 minutos

  3. Actividad de Seguridad Sospechosa

    • Condición: > 20 intentos de login fallidos en últimos 5 minutos

Troubleshooting​

No veo datos en OpenObserve​

  1. Verificar conexión:

    docker compose exec backend python scripts/diagnose_openobserve.py

  2. Verificar credenciales:

    grep OPENOBSERVE backend/.env

  3. Revisar logs del backend:

    docker compose logs backend | grep -i openobserve

  4. Probar envío manual:

    docker compose exec backend python scripts/test_openobserve.py

Los streams no aparecen​

  • Los streams se crean automáticamente al recibir el primer log
  • Si no aparecen, verifica:
    • El backend puede alcanzar OpenObserve
    • Las credenciales son correctas
    • No hay errores en los logs del backend

Errores de autenticación​

  1. Verificar que OPENOBSERVE_USER y OPENOBSERVE_PASSWORD coincidan
  2. Si cambiaste credenciales, recrear contenedor: 
    docker compose down openobserve
    rm -rf docker-volumes/openobserve/data
    docker compose up -d openobserve

Frontend no envía datos RUM​

  1. Verificar que VITE_OPENOBSERVE_CLIENT_TOKEN esté configurado
  2. Verificar que el token sea válido (RUM Token, no API Key)
  3. Reconstruir frontend: docker compose restart frontend
  4. Verificar consola del navegador para errores

Configuración Avanzada​

Rate Limiting​

# Limitar envío de logs (logs por segundo)
OPENOBSERVE_RATE_LIMIT=100

Batching​

# Tamaño del batch
OPENOBSERVE_BATCH_SIZE=50

# Intervalo para enviar batch automáticamente (segundos)
OPENOBSERVE_BATCH_INTERVAL=5.0

Timeouts y Retries​

# Timeout para requests (segundos)
OPENOBSERVE_TIMEOUT=5.0

# Número de reintentos
OPENOBSERVE_RETRIES=1

Documentación Completa​

Para más detalles, consulta:

Referencias​