Наблюдаемость
Libre WebUI предлагает операторам:
- структурированные журналы приложения в stdout/stderr;
- необязательный экспорт OpenTelemetry для HTTP-запросов, долговечных заданий, счётчиков и записей предупреждений и ошибок.
Ничего не отправляется проекту Libre WebUI. OpenTelemetry выключено до коллектора. Страницы Система и Использование читают локальное, не коллектор.
Структурированные журналы
LOG_FORMAT=text сохраняет обычную консоль. Установите LOG_FORMAT=json, чтобы получать по одному объекту JSON в строке:
LOG_LEVEL=info
LOG_FORMAT=json
Строка содержит:
- ISO-время;
- уровень и scope;
- сообщение;
- correlation id запроса или job; и
- ограниченные детали.
Каждый HTTP-запрос получает X-Request-Id. Входящий идентификатор принимается, если содержит 8–64 символа: буквы, цифры, ., _ или -; иначе создаётся UUID. Идентификатор возвращается в ответе и следует за асинхронной работой в контексте журналирования. Журнал доступа записывает метод, путь, состояние и длительность без строки запроса, поскольку параметры могут содержать пользовательские данные или краткосрочные учётные данные.
LOG_LEVEL принимает silent, error, warn, info или debug. Отладочный режим раскрывает дополнительные сведения; включайте его временно и защищайте журналы.
Граница редактирования
Детали и телеметрия проходят общий helper:
- поля, названия которых похожи на пароли, секреты, токены, ключи, авторизацию, файлы cookie, учётные данные, bearer-значения или JWT, пропускаются;
- строки до 512;
- arrays, depth, attribute count ограничены; и
- объект ошибки сохраняет имя и ограниченный текст сообщения, а не произвольный граф объектов.
Это дополнительная защита, а не разрешение журналировать промпты или секреты. Короткий пользовательский текст всё равно может попасть в обычную запись. Расширения должны записывать идентификаторы и результаты, а не тела запросов, промпты, документы, результаты инструментов или данные провайдеров. Ограничьте доступ и настройте политику хранения.
Включение OpenTelemetry
Libre напрямую экспортирует OTLP/HTTP JSON без SDK. Укажите HTTP base коллектора:
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer example-collector-token
OTEL_SERVICE_NAME=libre-webui
К базовому адресу добавляются /v1/traces, /v1/metrics и /v1/logs. OTEL_EXPORTER_OTLP_HEADERS — разделённый запятыми список пар key=value. Учётные данные коллектора храните как секреты развёртывания и не добавляйте в репозиторий. Значение OTEL_SERVICE_NAME по умолчанию — libre-webui.
Без переменной конечной точки запись ничего не делает и данные не покидают процесс. В командном развёртывании приложение и внешний рабочий процесс экспортируют независимо; настройте каждый процесс. Разные имена служб упрощают чтение панелей.
Экспортируемые сигналы
| Сигнал | Данные |
|---|---|
| Спаны HTTP-сервера | Метод и путь без строки запроса, состояние ответа, длительность, успех или ошибка и ID запроса |
| Счётчики HTTP | Монотонное число запросов по методу и классу состояния ответа |
| Спаны долговечных заданий | Тип задания, номер попытки, длительность и результат |
| Счётчики долговечных заданий | Число выполнений по типу и результату |
| Записи журнала | Отредактированные предупреждения и ошибки, область журнала и ID корреляции |
Спаны являются локальными завершёнными спанами. Libre пока не распространяет входящий родительский контекст трассировки, не строит деревья родительских и дочерних спанов между службами и не инструментирует отрисовку браузера или каждый вызов провайдера. Использование токенов и мультимедиа относится к локальным реестрам аналитики использования и управления расходами.
Доставка
Best-effort:
- буферы до 2,048 spans и 2,048 logs, удаляют старое;
- до 512 counter series;
- flush около пяти секунд;
- HTTP timeout три секунды; и
- ошибка collector удаляет batch, не блокируя запрос/job.
Это не журнал аудита и не долговечная система учёта. Для событий безопасности используйте журнал аудита только для добавления, для расходов — SQL-реестр использования, а для телеметрии — хранение и оповещения коллектора.
Устранение неполадок
Нет телеметрии. Проверьте OTEL_EXPORTER_OTLP_ENDPOINT в точном процессе, только base URL и OTLP/HTTP JSON на трёх путях.
Нет авторизации. Проверьте синтаксис заголовков, разделённых запятыми, и authorization=Bearer .... После изменения переменных окружения перезапустите процесс.
Запросы продолжают работать при недоступном коллекторе. Это ожидаемо: путь экспорта не блокирует приложение и не сохраняет неудачные пакеты для повторной отправки.
Поле исчезло/сократилось. Secret-shaped keys удаляются, длинные/глубокие ограничены. Логируйте безопасный ID.