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/web/setup-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 для каждой записи в стандартный вывод с базовыми полями среды и службы; общий уровень редактирования удаляет секреты до того, как будет выдана какая-либо строка.
Настройка и конфигурация
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/ключ и достижимость хоста с сервера.
Чтобы продолжить настройку, прочитайте Настройка кастомных доменов.