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


## Настройка и конфигурация

1. Установите SENTRY_DSN для отчётов об ошибках — исключения захватываются с correlation ID и тегами воркспейса.

2. Установите NEXT_PUBLIC_POSTHOG_KEY и NEXT_PUBLIC_POSTHOG_HOST для продуктовой аналитики — это публичные браузерные значения по дизайну.

3. Установите ALERT_WEBHOOK_URL на Slack-совместимый endpoint для оповещений о сбоях — приложение отправляет POST с JSON {text, name, severity, context}.

```
SENTRY_DSN=https://…@….ingest.sentry.io/…

NEXT_PUBLIC_POSTHOG_KEY=phc_…
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

ANALYTICS_PROVIDER=off    # off | local | plausible | posthog
# ANALYTICS_SITE_ID=
# ANALYTICS_HOST=

ALERT_WEBHOOK_URL=https://hooks.slack.com/services/…
```


## Рабочий процесс внедрения

Слой наблюдаемости очищает исключения и редактирует известные секретные ключи до пересылки — но свободный текст событий это ответственность автора, поэтому держите креденшелы вне имён событий и значений свойств.

Локальные адаптеры позволяют тестам проверять захваченные события и исключения без вызова Sentry или PostHog; ни одна из этих переменных не нужна для локальной работы.

Сигналы текут? Переходите к «Настройка кастомных доменов».


## Проверка и устранение неполадок

Вызовите тестовое исключение и подтвердите, что оно попадает в Sentry с вырезанными из полезной нагрузки секретами, затем проверьте, что подключённый сбой отправляет POST на ALERT_WEBHOOK_URL. Если события не приходят, проверьте пару DSN/ключ и достижимость хоста с сервера.


Чтобы продолжить настройку, прочитайте [Настройка кастомных доменов](https://supastack.dev/ru/docs/web/setup-domains.md).


## Вперёд

[Аудит, аналитика и ошибки](https://supastack.dev/ru/docs/modules/observability.md)