| 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) и скажи
об этом в отчёте.
- Настроен? В окружении заполнен
SENTRY_DSN (и SENTRY_FRONTEND_DSN для
фронта). Быстрая проверка: в старте бэкенда есть строка
Sentry enabled (env=…, release=…) — docker compose logs backend | grep -i "sentry enabled".
Если видишь Sentry disabled (SENTRY_DSN not set) — Sentry выключен, стоп.
- Жив и принимает? MCP-тул
find_projects(organizationSlug:"sentry") возвращает
tessera-backend (id 2) и tessera-frontend (id 3). Затем свежий search_issues
по нужному env что-то отдаёт по недавней активности.
- «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
(тег события), чтобы потом сопоставить с версией.
Поиск и анализ ошибок (триаж)
- Список проблем.
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.
- Детали issue (стек, теги, частота, пример события) —
get_sentry_resource
по issue id (вида TESSERA-BACKEND-XXX). Бэкенд-события несут теги
http.route/http.method/http.status_code/request_id (у 5xx) и
component/origin=background (у фоновых паник/ошибок) — по ним точно
локализуешь место.
request_id связывает issue с access-логом и slog-строкой fail() того же
запроса — удобно кросс-чекнуть по логам.- Глубокий разбор первопричины —
analyze_issue_with_seer (Seer): даёт гипотезу
корня и предлагаемый фикс. Полезно для незнакомых/странных стеков.
- После фикса —
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 лежит.
