Observabilité
Libre WebUI propose aux opérateurs deux voies d’observabilité :
- des journaux d’application structurés, écrits localement dans la sortie et l’erreur standard ;
- un exportateur OpenTelemetry facultatif pour les requêtes HTTP, les tâches durables, les compteurs et les enregistrements de journaux d’avertissement ou d’erreur.
Aucune de ces voies n’envoie de télémétrie au projet Libre WebUI. OpenTelemetry reste désactivé jusqu’à ce qu’un opérateur configure le point de terminaison d’un collecteur. Les pages d’administration Système et Utilisation sont distinctes : elles lisent les diagnostics et l’utilisation des modèles et fournisseurs depuis le déploiement lui-même plutôt que depuis un collecteur OpenTelemetry.
Journaux structurés
La valeur par défaut LOG_FORMAT=text conserve la sortie habituelle de la console,
organisée par portée. Définissez LOG_FORMAT=json pour obtenir un objet JSON par
ligne :
LOG_LEVEL=info
LOG_FORMAT=json
Chaque ligne structurée comprend :
- un horodatage ISO ;
- le niveau et la portée du journal ;
- un message ;
- l’identifiant de corrélation de la requête ou de la tâche durable actuelle, lorsqu’il existe ; et
- des détails structurés et limités fournis par l’appelant.
Chaque requête HTTP reçoit un X-Request-Id. Libre n’accepte un identifiant entrant
que s’il compte 8–64 caractères parmi des lettres, des chiffres, ., _ ou - ;
sinon, il crée un UUID. L’identifiant est renvoyé dans la réponse et accompagne le
travail asynchrone dans le contexte de journalisation. Les journaux d’accès
enregistrent la méthode HTTP, le chemin, l’état et la durée, sans la chaîne de
requête, car ses paramètres peuvent contenir du contenu utilisateur ou des
identifiants à courte durée de vie.
LOG_LEVEL accepte silent, error, warn, info ou debug. La journalisation
de débogage peut révéler davantage de détails d’exploitation ; ne l’activez que
pendant le diagnostic d’un problème et protégez les journaux produits comme les
autres données du déploiement.
Frontière de caviardage
Les détails structurés et la télémétrie exportée passent par la même fonction d’assistance de caviardage limité :
- les champs dont le nom ressemble à un mot de passe, un secret, un jeton, une clé, une autorisation, un cookie, un identifiant secret, une valeur bearer ou un JWT sont omis ;
- les chaînes sont limitées à 512 caractères ;
- la taille des tableaux, la profondeur d’imbrication et le nombre d’attributs exportés sont limités ; et
- les objets d’erreur conservent leur nom et un message limité, mais pas un graphe d’objets arbitraire.
Il s’agit d’une défense en profondeur, pas d’une autorisation à journaliser les invites ou les secrets. Une courte chaîne fournie par l’utilisateur, placée dans un champ dont le nom n’évoque pas un secret, peut tout de même apparaître comme texte ordinaire dans le journal. Les extensions de l’application doivent journaliser les identifiants et les résultats plutôt que les corps de requêtes, les invites, le texte des documents, les résultats des outils ou les charges utiles des fournisseurs. Limitez l’accès aux journaux et appliquez une politique de conservation gérée par l’opérateur.
Activer OpenTelemetry
Libre exporte directement du JSON OTLP/HTTP, sans ajouter de dépendance au SDK OpenTelemetry. Faites-le pointer vers l’URL HTTP de base d’un collecteur qui accepte les chemins de signaux standard :
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer example-collector-token
OTEL_SERVICE_NAME=libre-webui
L’exportateur ajoute /v1/traces, /v1/metrics et /v1/logs à l’URL de base.
OTEL_EXPORTER_OTLP_HEADERS est une liste de paires key=value séparées par des
virgules. Stockez les identifiants du collecteur comme secrets du déploiement ; ne
les validez pas dans le dépôt. La valeur par défaut de OTEL_SERVICE_NAME est
libre-webui.
En l’absence de la variable du point de terminaison, l’enregistrement des spans, métriques et journaux n’effectue aucune opération, et rien ne quitte le processus. Dans un déploiement en équipe, les processus de l’application et des workers externes exportent indépendamment ; donnez à chaque processus la configuration de collecteur qu’il doit utiliser. Un nom de service distinct pour chaque rôle peut faciliter la lecture des tableaux de bord.
Signaux exportés
| Signal | Données enregistrées par Libre |
|---|---|
| Spans du serveur HTTP | Méthode et chemin sans chaîne de requête, état de la réponse, durée, réussite ou échec et identifiant de requête |
| Compteurs HTTP | Nombre monotone de requêtes par méthode et classe d’état de réponse |
| Spans des tâches durables | Type de tâche, numéro de tentative, durée et réussite ou échec |
| Compteurs des tâches durables | Nombre monotone d’exécutions par type de tâche et résultat |
| Enregistrements de journaux | Messages d’avertissement et d’erreur caviardés, avec portée du journal et identifiants de corrélation de requête ou de tâche |
Les spans sont des spans locaux terminés. Libre ne propage pas encore un parent de trace OpenTelemetry entrant, ne crée pas d’arborescence de spans parents et enfants entre services et n’instrumente ni le rendu du navigateur ni chaque appel aux fournisseurs. L’utilisation des jetons de modèles et des médias relève plutôt des registres locaux d’analyse de l’utilisation et de gouvernance des coûts.
Comportement de la livraison
La télémétrie fonctionne délibérément au mieux :
- les tampons contiennent au maximum 2,048 spans et 2,048 enregistrements de journaux, et abandonnent l’entrée la plus ancienne en cas de pression ;
- au maximum 512 séries de compteurs sont conservées ;
- l’exportateur vide ses tampons environ toutes les cinq secondes ;
- chaque exportation HTTP expire au bout de trois secondes ; et
- une erreur du collecteur abandonne le lot concerné sans jamais bloquer ni faire échouer une requête de l’application ou une tâche durable.
L’exportateur ne constitue donc ni un journal d’audit ni un système de comptabilité durable. Utilisez le journal d’audit de sécurité en ajout seul pour les événements de sécurité, le registre d’utilisation SQL pour les coûts, et les fonctions de conservation et d’alerte de votre collecteur pour la télémétrie.
Dépannage
Aucune télémétrie n’arrive. Vérifiez que OTEL_EXPORTER_OTLP_ENDPOINT est présent
dans l’environnement du processus exact de l’application ou du worker, ne contient
que l’URL de base du collecteur et que celui-ci accepte le JSON OTLP/HTTP sur les
trois chemins standard.
Le collecteur renvoie une erreur d’autorisation. Vérifiez la syntaxe des en-têtes
séparés par des virgules et si le collecteur attend authorization=Bearer ... ou un
autre en-tête. Redémarrez le processus après avoir modifié les variables
d’environnement.
Les requêtes réussissent encore lorsque le collecteur est indisponible. C’est le comportement attendu. Le chemin d’exportation échoue de manière ouverte pour préserver la disponibilité de l’application et ne conserve pas les lots en échec pour les réessayer.
Un champ de journal est absent ou raccourci. Les clés évoquant un secret sont supprimées et les valeurs longues ou profondément imbriquées sont limitées par conception. Journalisez un identifiant ou un résumé sûr au lieu d’affaiblir la frontière de caviardage.