> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# Аудит, аналитика и ошибки

Понимайте активность с контекстом воркспейса и очищенными данными событий.

## Найдите полезную информацию, когда действие не удалось

Наблюдаемость означает наблюдение за тем, что делает ваше приложение. Начните с терминала, на котором работает ваш веб-сервер: повторите одно неудачное действие и прочитайте первую ошибку и любой идентификатор корреляции, метку, связывающую сообщения из одного и того же запроса. Поделитесь командой, временем и устраненной ошибкой при обращении за помощью; не делитесь файлами .env или токенами.

Для размещенных отчетов об ошибках следуйте разделу «Работоспособность и операции», чтобы настроить поддерживаемые параметры мониторинга в apps/web/.env.local или на панели мониторинга среды хоста. Сохраните и перезапустите сервер. Запустите сбой контролируемого теста в тестовой среде и убедитесь, что он появляется в правильном контексте рабочей области. Настраиваемый мониторинг не подтверждает получение события.

ALERT_WEBHOOK_URL — это дополнительный пункт назначения HTTPS для оповещений о сбоях доставки заданий и терминалов через веб-перехватчик. Если вам это нужно, создайте совместимую входящую конечную точку и сохраните ее URL на стороне сервера; в противном случае оставьте его пустым. Попросите агента смоделировать один сбой и подтвердить ровно одно оповещение без каких-либо секретов в его тексте. Не инициируйте платную работу или сбои в учетных записях клиентов для этого теста.

[Проверьте работоспособность и рабочие настройки приложения](https://supastack.dev/ru/docs/web/security.md)

[Диагностика ошибки в локальном терминале](https://supastack.dev/ru/docs/web/troubleshooting.md)


## Ведите аудит-лог воркспейса

Записи аудита фиксируют изменения вроде обновлений конфигурации провайдеров внутри воркспейса. Разрешайте аутентифицированный воркспейс до чтения или записи этих записей и сохраняйте эту область при добавлении продуктовых событий.

Записывайте действие и идентификаторы, нужные для его понимания. Креденшелы провайдеров и другие чувствительные значения должны оставаться вне полезной нагрузки аудита и логов.


## Захватывайте продуктовые события

Пакет наблюдаемости предоставляет адаптер 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 для каждой записи в стандартный вывод с базовыми полями среды и службы; общий уровень редактирования удаляет секреты до того, как будет выдана какая-либо строка.


## Вперёд

[Чек-лист развёртывания](https://supastack.dev/ru/docs/web/deployment.md)