Observabilidad
Libre WebUI ofrece dos rutas de observabilidad para operadores:
- registros estructurados de la aplicación, escritos localmente en la salida y el error estándar;
- un exportador OpenTelemetry opcional para solicitudes HTTP, trabajos duraderos, contadores y registros de advertencias o errores.
Ninguna ruta envía telemetría al proyecto Libre WebUI. OpenTelemetry permanece desactivado hasta que el operador configura un endpoint de recopilación. Las páginas administrativas de Sistema y Uso son independientes: leen el diagnóstico y uso desde el despliegue, no desde un recopilador OpenTelemetry.
Registros estructurados
El valor predeterminado LOG_FORMAT=text conserva la salida habitual por ámbitos.
Define LOG_FORMAT=json para obtener un objeto JSON por línea:
LOG_LEVEL=info
LOG_FORMAT=json
Cada línea estructurada contiene:
- una marca de tiempo ISO;
- nivel y ámbito del registrador;
- un mensaje;
- el ID de correlación de la solicitud o el trabajo duradero actual, si existe; y
- detalles estructurados y acotados proporcionados por quien llama.
Cada solicitud HTTP recibe un X-Request-Id. Libre solo acepta un ID entrante de
8–64 caracteres formados por letras, números, ., _ o -; en caso contrario,
crea un UUID. El ID se devuelve y acompaña el trabajo asíncrono en el contexto de
registro. Los accesos registran método, ruta, estado y duración sin la cadena de
consulta, porque sus parámetros pueden contener datos del usuario o credenciales
efímeras.
LOG_LEVEL admite silent, error, warn, info o debug. El nivel de
depuración puede revelar más detalles operativos; actívalo solo al diagnosticar un
problema y protege los registros como cualquier otro dato del despliegue.
Límite de censura
Los detalles estructurados y la telemetría exportada pasan por el mismo asistente de censura acotada:
- se omiten los campos cuyos nombres parecen contraseñas, secretos, tokens, claves, autorización, cookies, credenciales, valores bearer o JWT;
- las cadenas se limitan a 512 caracteres;
- se acotan los arrays, la profundidad y el número de atributos exportados; y
- los objetos de error conservan su nombre y un mensaje acotado, no un grafo arbitrario.
Es defensa en profundidad, no permiso para registrar prompts o secretos. Una cadena corta proporcionada por el usuario en un campo cuyo nombre no parezca secreto aún puede aparecer como texto normal. Las extensiones deben registrar identificadores y resultados, no cuerpos, prompts, texto de documentos, resultados de herramientas o cargas de proveedores. Restringe el acceso y aplica una política de conservación.
Activar OpenTelemetry
Libre exporta OTLP/HTTP JSON directamente, sin añadir una dependencia del SDK de OpenTelemetry. Apunta a la URL HTTP base de un recopilador que acepte las rutas estándar:
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer example-collector-token
OTEL_SERVICE_NAME=libre-webui
El exportador añade /v1/traces, /v1/metrics y /v1/logs a la URL base.
OTEL_EXPORTER_OTLP_HEADERS es una lista de pares key=value separados por comas.
Guarda las credenciales como secretos del despliegue; no las confirmes en el
repositorio. OTEL_SERVICE_NAME usa libre-webui de forma predeterminada.
Cuando falta la variable del endpoint, el registro de spans, métricas y logs no hace nada y nada abandona el proceso. En un despliegue de equipo, la aplicación y los workers externos exportan por separado; proporciona a cada proceso la configuración que deba usar. Un nombre de servicio distinto por rol puede facilitar la lectura de los paneles.
Señales exportadas
| Señal | Qué registra Libre |
|---|---|
| Spans del servidor HTTP | Método y ruta sin consulta, estado de respuesta, duración, éxito o fallo e ID de solicitud |
| Contadores HTTP | Recuento monótono de solicitudes por método y clase de estado |
| Spans de trabajos duraderos | Tipo de trabajo, número de intento, duración y éxito o fallo |
| Contadores de trabajos duraderos | Recuento monótono de ejecuciones por tipo y resultado |
| Registros | Advertencias y errores censurados con ámbito e ID de correlación de solicitud o trabajo |
Los spans son locales y ya terminados. Libre no propaga actualmente un padre de traza entrante, no crea árboles padre/hijo entre servicios ni instrumenta el render del navegador y cada llamada a proveedores. El uso de tokens y medios pertenece a los registros locales de Análisis de uso y Gobernanza de costes.
Comportamiento de entrega
La telemetría es deliberadamente de mejor esfuerzo:
- los búferes guardan como máximo 2,048 spans y 2,048 registros, y descartan el más antiguo bajo presión;
- se conservan como máximo 512 series de contadores;
- el exportador vacía los búferes aproximadamente cada cinco segundos;
- cada exportación HTTP tiene un tiempo de tres segundos; y
- un error del recopilador descarta ese lote sin bloquear ni hacer fallar una solicitud o trabajo.
Por ello, el exportador no es un registro de auditoría ni un sistema contable duradero. Usa el registro de auditoría de seguridad de solo anexado para sucesos de seguridad, el registro SQL de uso para costes y la conservación y alertas del recopilador para telemetría.
Solución de problemas
No llega telemetría. Confirma que OTEL_EXPORTER_OTLP_ENDPOINT esté en el entorno
del proceso exacto de la aplicación o worker, contenga solo la URL base y que el
recopilador acepte OTLP/HTTP JSON en las tres rutas estándar.
El recopilador responde «no autorizado». Comprueba la sintaxis de cabeceras
separadas por comas y si espera authorization=Bearer ... u otra cabecera. Reinicia
el proceso tras cambiar variables de entorno.
Las solicitudes siguen funcionando si el recopilador cae. Es lo esperado. La ruta de exportación falla de forma abierta para mantener la disponibilidad y no conserva lotes fallidos para reintentarlos.
Falta un campo o está acortado. Se eliminan claves que parecen secretos y se acotan valores largos o anidados. Registra un identificador o resumen seguro en vez de debilitar el límite de censura.