For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ru/docs/modules/observability.md (or send Accept: text/markdown).
Аудит, аналитика и ошибки
Понимайте активность с контекстом воркспейса и очищенными данными событий.
Найдите полезную информацию, когда действие не удалось
Наблюдаемость означает наблюдение за тем, что делает ваше приложение. Начните с терминала, на котором работает ваш веб-сервер: повторите одно неудачное действие и прочитайте первую ошибку и любой идентификатор корреляции, метку, связывающую сообщения из одного и того же запроса. Поделитесь командой, временем и устраненной ошибкой при обращении за помощью; не делитесь файлами .env или токенами.
Для размещенных отчетов об ошибках следуйте разделу «Работоспособность и операции», чтобы настроить поддерживаемые параметры мониторинга в apps/web/.env.local или на панели мониторинга среды хоста. Сохраните и перезапустите сервер. Запустите сбой контролируемого теста в тестовой среде и убедитесь, что он появляется в правильном контексте рабочей области. Настраиваемый мониторинг не подтверждает получение события.
ALERT_WEBHOOK_URL — это дополнительный пункт назначения HTTPS для оповещений о сбоях доставки заданий и терминалов через веб-перехватчик. Если вам это нужно, создайте совместимую входящую конечную точку и сохраните ее URL на стороне сервера; в противном случае оставьте его пустым. Попросите агента смоделировать один сбой и подтвердить ровно одно оповещение без каких-либо секретов в его тексте. Не инициируйте платную работу или сбои в учетных записях клиентов для этого теста.
Ведите аудит-лог воркспейса
Записи аудита фиксируют изменения вроде обновлений конфигурации провайдеров внутри воркспейса. Разрешайте аутентифицированный воркспейс до чтения или записи этих записей и сохраняйте эту область при добавлении продуктовых событий.
Записывайте действие и идентификаторы, нужные для его понимания. Креденшелы провайдеров и другие чувствительные значения должны оставаться вне полезной нагрузки аудита и логов.
Захватывайте продуктовые события
Пакет наблюдаемости предоставляет адаптер AnalyticsClient и значения AnalyticsEvent в области воркспейса. Каждое событие несёт имя, отдельную идентичность, workspaceId и необязательные свойства.
Используйте createObservability для маршрутизации событий через настроенный клиент аналитики. Структурированные свойства очищаются до доставки; держите чувствительный свободный текст также вне имён событий и значений свойств.
Сообщайте об ошибках с безопасным контекстом
ErrorClient захватывает исключения с тегами workspaceId и структурированным дополнительным контекстом. Общий слой наблюдаемости очищает исключения и редактирует чувствительный контекст до пересылки настроенному клиенту.
Используйте локальные адаптеры для проверки захваченных событий и исключений без вызова провайдера мониторинга. Тестируйте, что теги воркспейса остаются и креденшелы удалены, до включения внешнего назначения.
Отслеживание запроса по задачам, заданиям и веб-перехватчикам
Границы входа создают идентификатор корреляции corr_<uuid>, который связывает исходный запрос с работой, которую он запускает. При отправке AI-задачи идентификатор отмечается в полезных данных задачи и событии ai_task_submit, каждый получатель веб-перехватчика для выставления счетов создает один веб-перехватчик для каждого запроса, а планировщик создает один для каждого отправленного задания.
Один и тот же идентификатор используется в свойствах событий job.completed и ai_task_completed, дополнительных функциях captureException, полезной нагрузке реестра webhook_event и каждой мета полезной нагрузки webhook_delivery — поэтому он попадает в подписанное тело, которое получает подписчик. Отсутствующие или неправильно сформированные идентификаторы допускаются: потребитель создает новый идентификатор вместо того, чтобы отклонять старые строки.
Оповещение о реальных сбоях
Установите для ALERT_WEBHOOK_URL любую конечную точку HTTPS, которая принимает JSON POST в форме {текст, имя, серьезность, контекст}; входящий веб-перехватчик в стиле Slack работает как есть. Оповещения выполняются по принципу «выпустил и забыл» с пятисекундным тайм-аутом, при неудачной доставке регистрируется одно консольное предупреждение, а оповещение выдает сигнал, пока переменная не установлена.
Отправленные оповещения — job.failed (предупреждение — обработчик задания сгенерировал или тип задания неизвестен) и webhook.delivery_failed (критическое — только когда исходящая доставка достигает сбоя терминала после последней попытки; обычные повторные попытки остаются без ответа, и каждая строка доставки выдает предупреждение не более одного раза).
Измеряйте продолжительность и транслируйте структурированные журналы
serverObservability.measure рассчитывает время асинхронной операции и генерирует аналитическое событие <name>.duration, переносящее значение periodMs — в случае успеха или неудачи, без маскировки исходной ошибки. Выполнение задания ai.task.execute уже завершено, поэтому продолжительность выполнения задачи попадает в настроенный клиент аналитики.
serverObservability.logger записывает одну строку JSON для каждой записи в стандартный вывод с базовыми полями среды и службы; общий уровень редактирования удаляет секреты до того, как будет выдана какая-либо строка.