tessera-sentry

name	tessera-sentry
description	Поиск и анализ ошибок бэкенда/фронта Tessera и верификация фиксов через self-hosted Sentry (MCP-сервер sentry-self-hosted). Использовать при диагностике internal error / 5xx / паник, при проверке, что фикс убрал ошибку, и чтобы понять реальную частоту/стек проблемы — НО только когда Sentry настроен и работает. Иначе откатываться на логи.

tessera-sentry

Как агенту пользоваться self-hosted Sentry для триажа ошибок и верификации фиксов через MCP-сервер sentry-self-hosted (тулы search_issues, search_events, get_sentry_resource, analyze_issue_with_seer, update_issue, find_projects, execute_sentry_tool).

Бэкенд ловит любой 5xx + c.Error() (middleware.SentryReport) и паники фоновых горутин (observability.CapturePanic/Recover, воркеры/WS/синк/джобы) — так что почти любой internal error оседает в Sentry как issue. Это первичный источник правды об ошибках, точнее и быстрее, чем грепать логи контейнера.

Гейтинг — использовать ТОЛЬКО когда Sentry настроен и жив

Прежде чем полагаться на Sentry, убедись, что он реально принимает события. Если нет — не трать время, работай по логам (docker compose logs backend) и скажи об этом в отчёте.

1. Настроен? В окружении заполнен SENTRY_DSN (и SENTRY_FRONTEND_DSN для фронта). Быстрая проверка: в старте бэкенда есть строка Sentry enabled (env=…, release=…) — docker compose logs backend | grep -i "sentry enabled". Если видишь Sentry disabled (SENTRY_DSN not set) — Sentry выключен, стоп.
2. Жив и принимает? MCP-тул find_projects(organizationSlug:"sentry") возвращает tessera-backend (id 2) и tessera-frontend (id 3). Затем свежий search_issues по нужному env что-то отдаёт по недавней активности.
3. «200 от relay ≠ долетело». Sentry-ingress отвечает клиенту 200 даже когда событие дальше не доходит до хранилища (сломанный конвейер/DSN). Поэтому «проверка доставки» = событие реально видно через search_issues/search_events, а НЕ то, что бэкенд залогировал ошибку. Если бэкенд пишет ошибку, а в Sentry её нет — см. гочу про mirrored-сеть ниже и откатись на логи.

Проекты и организация

• Организация (organizationSlug): sentry.
• Проекты (projectSlugOrId): tessera-backend (бэкенд, Go, id 2) и tessera-frontend (веб, Vue, id 3). internal (id 1) — сам Sentry, игнор.
• Тег окружения (environment) — из SENTRY_ENV/APP_ENV; у локального инстанса это localhost. Всегда фильтруй по env, чтобы не смешать инсталляции (см. ниже).

Несколько окружений в одном Sentry

Один Sentry-проект собирает события сразу с нескольких окружений (environment): локальный localhost, а также боевые/стейджинг-инсталляции (напр. production на tessera.msdnna.website) и др. — они шлют в те же проекты tessera-backend/ tessera-frontend, различаясь только тегом env.

• При локальном тестировании и обычной работе агента — акцент строго на environment:localhost (инстанс Tessera на этой машине, который ты и правишь). Всегда добавляй environment:localhost в query, иначе смешаешь чужие инсталляции.
• Ошибки с ДРУГИХ окружений — вспомогательный сигнал, не основной. Их можно принимать во внимание (реальные баги в проде, которые стоит завести отдельной задачей — см. ниже), но трактовать осторожно: там развёрнута неизвестная версия Tessera (не обязательно текущий develop), поэтому стек/строки могут не совпадать с кодом под рукой, а «ошибка» — быть уже исправленной или относиться к другому релизу. Не верифицируй свой локальный фикс по не-localhost событиям.
• Если берёшь прод-ошибку в работу — в задаче укажи её env и, если видно, release (тег события), чтобы потом сопоставить с версией.

Поиск и анализ ошибок (триаж)

1. Список проблем. search_issues(organizationSlug:"sentry", projectSlugOrId:"tessera-backend", query:"is:unresolved environment:localhost level:error", sort:"freq"). Синтаксис: is:unresolved|resolved|ignored, firstSeen:-24h, lastSeen:-7d, level:error, environment:…, release:…. Для счётчиков/агрегатов и отдельных событий с таймстампами — search_events, не search_issues.
2. Детали issue (стек, теги, частота, пример события) — get_sentry_resource по issue id (вида TESSERA-BACKEND-XXX). Бэкенд-события несут теги http.route/http.method/http.status_code/request_id (у 5xx) и component/origin=background (у фоновых паник/ошибок) — по ним точно локализуешь место.
3. request_id связывает issue с access-логом и slog-строкой fail() того же запроса — удобно кросс-чекнуть по логам.
4. Глубокий разбор первопричины — analyze_issue_with_seer (Seer): даёт гипотезу корня и предлагаемый фикс. Полезно для незнакомых/странных стеков.
5. После фикса — update_issue(status:"resolved", reason:"…"); если это ожидаемый шум — status:"ignored". Не «прибирай» чужие issue без причины.

Верификация фиксов и фич через Sentry

Sentry — это ещё и приёмочная проверка: «после фикса ошибка больше не воспроизводится».

• До фикса: найди/запомни issue и его lastSeen + счётчик событий (и/или request_id конкретного репро).
• Сделай фикс, воспроизведи сценарий (та же ручка/действие).
• После: search_events/search_issues по тому же отпечатку за окно ПОСЛЕ деплоя фикса. Успех = новых событий нет (lastSeen не двигается), при работающем ingress (гейтинг п.3). Затем update_issue(resolved).
• Помни про группировку: 5xx-события бэкенда фингерпринтятся по route+method+status, так что все 500 одной ручки — один issue. «Ушло» = именно этот issue перестал получать события, а не «стало меньше вообще».
• Sentry дополняет, но НЕ заменяет функциональную проверку (e2e/CDP/скрин из tessera-e2e): он говорит «ошибок нет», а не «фича делает то, что нужно».

Побочные / незнакомые ошибки → отдельная задача в Tessera

Если при работе (в Sentry или в логах) всплыла ошибка, не связанная напрямую с текущей задачей — незнакомый стек, чужая ручка, странная паника, — не чини её молча и не игнорируй. Заведи отдельную задачу в Tessera на последующий разбор, чтобы такие ошибки минимизировались:

• tessera_create_task(board_id|workspace_id, title:"…", description:"…", priority:…, tags:[…]) — короткий заголовок из сути ошибки; в описании: проект и env Sentry, issue id/ссылка, http.route/component, стек/request_id, частота (firstSeen/lastSeen/счётчик) и гипотеза Seer, если есть.
• По возможности пометь тегом (напр. bug/sentry) для группировки.
• Если ошибка соприкасается с текущей задачей — свяжи: tessera_link_tasks(kind:"relates").
• Ведение задач и возврат на проверку — по скиллу tessera-task-workflow.

Не плоди дубли: перед созданием глянь, нет ли уже такой задачи (tessera_list_tasks по тегу/тексту).

Гочи

• Mirrored-сеть WSL ломает доставку в Sentry. Если host.docker.internal в SENTRY_DSN, а WSL в networkingMode=mirrored, события бесшумно теряются на входе (SDK рапортует успех, в Sentry пусто). Фикс — LAN-IP машины в SENTRY_DSN/SENTRY_FRONTEND_DSN. Подробности и способ проверки конвейера — в auto-memory reference-wsl-mirrored-sentry-dsn. Симптом для агента: бэкенд логирует ошибку, а search_issues её не показывает → доверяй логам, не Sentry, и отметь это.
• Фильтр по env обязателен — иначе смешаешь dev/боевую. dev обычно localhost.
• Новые MCP-тулы Sentry подхватываются после реконнекта клиента, не в текущей сессии.
• Не лезь чинить сам стек Sentry (kafka/relay/consumers) без явной просьбы — это инфраструктура вне репо Tessera; максимум зафиксируй, что ingress лежит.