Logging

Mayros registra en dos lugares:

Logs de archivos (líneas JSON) escritos por el Gateway.
Salida de consola mostrada en terminales y la UI de Control.

Esta página explica dónde viven los logs, cómo leerlos y cómo configurar niveles y formatos de log.

Dónde viven los logs

Por defecto, el Gateway escribe un archivo de log rotativo en:

/tmp/mayros/mayros-YYYY-MM-DD.log

La fecha usa la zona horaria local del host del gateway.

Puedes anular esto en ~/.mayros/mayros.json:

json
{
  "logging": {
    "file": "/path/to/mayros.log"
  }
}

Cómo leer los logs

CLI: seguimiento en vivo (recomendado)

Usa el CLI para hacer tail del archivo de log del gateway vía RPC:

bash
mayros logs --follow

Modos de salida:

Sesiones TTY: líneas de log estructuradas, bonitas y coloreadas.
Sesiones no-TTY: texto plano.
--json: JSON delimitado por líneas (un evento de log por línea).
--plain: forzar texto plano en sesiones TTY.
--no-color: desactivar colores ANSI.

En modo JSON, el CLI emite objetos etiquetados por type:

meta: metadatos del stream (archivo, cursor, tamaño)
log: entrada de log parseada
notice: sugerencias de truncamiento / rotación
raw: línea de log sin parsear

Si el Gateway no está alcanzable, el CLI imprime una sugerencia corta para ejecutar:

bash
mayros doctor

UI de Control (web)

La pestaña Logs de la UI de Control hace tail del mismo archivo usando logs.tail. Consulta /web/control-ui para saber cómo abrirla.

Logs solo de canal

Para filtrar actividad de canal (WhatsApp/Telegram/etc), usa:

bash
mayros channels logs --channel whatsapp

Formatos de log

Logs de archivo (JSONL)

Cada línea en el archivo de log es un objeto JSON. El CLI y la UI de Control parsean estas entradas para renderizar salida estructurada (hora, nivel, subsistema, mensaje).

Salida de consola

Los logs de consola son conscientes de TTY y formateados para legibilidad:

Prefijos de subsistema (p.ej. gateway/channels/whatsapp)
Coloreado por nivel (info/warn/error)
Modo compacto o JSON opcional

El formato de consola está controlado por logging.consoleStyle.

Configurar logging

Toda la configuración de logging vive bajo logging en ~/.mayros/mayros.json.

json
{
  "logging": {
    "level": "info",
    "file": "/tmp/mayros/mayros-YYYY-MM-DD.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty",
    "redactSensitive": "tools",
    "redactPatterns": ["sk-.*"]
  }
}

Niveles de log

logging.level: nivel de logs de archivo (JSONL).
logging.consoleLevel: nivel de verbosidad de consola.

--verbose solo afecta la salida de consola; no cambia los niveles de log de archivo.

Estilos de consola

logging.consoleStyle:

pretty: amigable para humanos, coloreado, con marcas de tiempo.
compact: salida más ajustada (mejor para sesiones largas).
json: JSON por línea (para procesadores de log).

Redacción

Los resúmenes de herramientas pueden redactar tokens sensibles antes de que lleguen a la consola:

logging.redactSensitive: off | tools (predeterminado: tools)
logging.redactPatterns: lista de cadenas regex para anular el conjunto predeterminado

La redacción afecta solo la salida de consola y no altera los logs de archivo.

Los diagnósticos son eventos estructurados y legibles por máquina para ejecuciones de modelo y telemetría de flujo de mensajes (webhooks, encolado, estado de sesión). No reemplazan los logs; existen para alimentar métricas, trazas y otros exportadores.

Los eventos de diagnóstico se emiten en proceso, pero los exportadores solo se adjuntan cuando los diagnósticos + el plugin exportador están habilitados.

OpenTelemetry vs OTLP

OpenTelemetry (OTel): el modelo de datos + SDKs para trazas, métricas y logs.
OTLP: el protocolo de cable usado para exportar datos OTel a un collector/backend.
Mayros exporta vía OTLP/HTTP (protobuf) hoy.

Señales exportadas

Métricas: contadores + histogramas (uso de tokens, flujo de mensajes, encolado).
Trazas: spans para uso de modelo + procesamiento de webhook/mensaje.
Logs: exportados sobre OTLP cuando diagnostics.otel.logs está habilitado. El volumen de log puede ser alto; ten en cuenta logging.level y filtros del exportador.

Catálogo de eventos de diagnóstico

Uso de modelo:

model.usage: tokens, costo, duración, contexto, proveedor/modelo/canal, IDs de sesión.

Flujo de mensajes:

webhook.received: ingreso de webhook por canal.
webhook.processed: webhook manejado + duración.
webhook.error: errores del manejador de webhook.
message.queued: mensaje encolado para procesamiento.
message.processed: resultado + duración + error opcional.

Cola + sesión:

queue.lane.enqueue: encolar carril de cola de comandos + profundidad.
queue.lane.dequeue: desencolar carril de cola de comandos + tiempo de espera.
session.state: transición de estado de sesión + razón.
session.stuck: advertencia de sesión atascada + edad.
run.attempt: metadatos de reintento/intento de ejecución.
diagnostic.heartbeat: contadores agregados (webhooks/cola/sesión).

Habilitar diagnósticos (sin exportador)

Usa esto si quieres eventos de diagnóstico disponibles para plugins o sumideros personalizados:

json
{
  "diagnostics": {
    "enabled": true
  }
}

Banderas de diagnósticos (logs dirigidos)

Usa banderas para activar logs de depuración extra y dirigidos sin elevar logging.level. Las banderas no distinguen mayúsculas de minúsculas y soportan comodines (p.ej. telegram.* o *).

json
{
  "diagnostics": {
    "flags": ["telegram.http"]
  }
}

Anulación de entorno (una vez):

MAYROS_DIAGNOSTICS=telegram.http,telegram.payload

Notas:

Los logs de banderas van al archivo de log estándar (igual que logging.file).
La salida aún se redacta según logging.redactSensitive.
Guía completa: /diagnostics/flags.

Exportar a OpenTelemetry

Los diagnósticos se pueden exportar vía el plugin diagnostics-otel (OTLP/HTTP). Esto funciona con cualquier collector/backend de OpenTelemetry que acepte OTLP/HTTP.

json
{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": {
      "diagnostics-otel": {
        "enabled": true
      }
    }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://otel-collector:4318",
      "protocol": "http/protobuf",
      "serviceName": "mayros-gateway",
      "traces": true,
      "metrics": true,
      "logs": true,
      "sampleRate": 0.2,
      "flushIntervalMs": 60000
    }
  }
}