コンテンツにスキップ

2026-04 Sentry workflow alert automation 要件

背景

  • 本 repo では Sentry release / sourcemap / feedback / diagnostics / Logs / browser failed request capture までは実装済みだが、通知ルールは SaaS UI へ閉じており、再現性のあるレビュー対象になっていなかった。
  • 現時点では OpenAI / Anthropic / LangChain / Vercel AI / Google GenAI / Pydantic AI を利用していないため、Sentry の AI monitoring は対象外とする。
  • OTel exporter は collector / routing 基盤を新設しない限り運用判断ができないため、別途 observability 設計の合意が出るまで対象外とする。

合意事項

1. 正本

  • Sentry workflow alert の checked-in 正本は observability/sentry-workflow-alerts.json とする。
  • workflow の list / upsert は scripts/ops/sentry-workflow-alerts.mjs からのみ実行する。
  • root の運用入口は just sentry-alerts-list / just sentry-alerts-upsert-dry-run / just sentry-alerts-upsert / just sentry-live-config-audit とする。
  • local の just sentry-alerts-list / just sentry-alerts-upsert は login 済みの sentry user auth を既定で使い、CI で SENTRY_AUTH_TOKEN が注入されている場合のみ token transport を使う。
  • org slug と base URL は root .sentryclirc の既定値（org=ritsubi, url=https://sentry.io/）を正とし、必要時のみ SENTRY_ORG / SENTRY_URL で上書きする。

2. 認証と適用前提

  • local は sentry whoami が通る user auth を既定とし、token を必須にしない。
  • CI で SENTRY_AUTH_TOKEN を使う場合は 少なくとも alerts:write scope を持つこと。
  • local / CI ともに token をコードへ保存しない。開発中の確認は --dry-run を使い、payload と upsert plan を確認してから live apply する。
  • 通知の既定 target は issue_owners、owner が無い場合は Active Members へ email fallthrough する。
  • current ritsubi org では local user auth から Slack integration が見えていないため、 repo-managed workflow の既定通知は email とする。

3. 初期 workflow セット

  • 初期セットは production 限定 の conservative default とし、以下 5 本を正規運用とする。
  • Production high-priority issue notifications
    • trigger: first_seen_event / regression_event / reappeared_event
    • condition: issue_priority >= High(75) かつ level >= error
    • action: email to issue_owners（fallback: Active Members）
  • Production storefront vendure dependency failure spike
    • trigger: first_seen_event / regression_event / reappeared_event
    • condition: dependency.name=vendure、area=vendure-fetch、flow=graphql、 level >= error、event_frequency_count >= 20 / 1h
    • action: email to issue_owners（fallback: Active Members）
  • Production storefront /products browse issue notifications
    • trigger: first_seen_event / regression_event / reappeared_event
    • condition: storefront.products.route=/products かつ level >= error
    • action: email to issue_owners（fallback: Active Members）
  • Production storefront browser error boundary issue notifications
    • trigger: first_seen_event / regression_event / reappeared_event
    • condition: area=storefront-error-boundary、storefront.runtime=client、 level >= error
    • action: email to issue_owners（fallback: Active Members）
  • Production react dashboard browser issue notifications
    • trigger: first_seen_event / regression_event / reappeared_event
    • condition: service=react-dashboard、surface=react-dashboard、level >= error
    • action: email to issue_owners（fallback: Active Members）

4. 運用ルール

  • 適用前に just sentry-alerts-upsert-dry-run を実行し、review 可能な plan を確認する。
  • 実適用後は just sentry-alerts-list で name / frequency / target を確認する。
  • upsert は workflow 名で既存 rule を照合し、同名があれば更新・無ければ新規作成する。
  • 同名 workflow が複数存在して曖昧な場合は fail し、手動で整理してから再実行する。
  • live apply は just sentry-alerts-upsert を正式入口とし、--json などの追加 option は just sentry-alerts-list --json のようにそのまま渡す。
  • workflow description には、最低 1 つは初動で叩く just recipe か runbook 名を含め、 alert を見た operator が Sentry UI からそのまま次の切り分け導線へ進めるようにする。
  • checked-in workflow と live state の drift 確認は just sentry-live-config-audit --allow-drift --json を使う。

5. 検知レイヤー上の位置づけ

  • 本 workflow alert automation は notification / escalation layer であり、 以下を置き換えない。
  • readiness contract
  • dashboard admin API canary
  • browser synthetic
  • storefront business-canary / KPI proxy lane
  • subtle error detection は「gate と継続監視で先に止める」+「Sentry browser/runtime alert で first_seen / regression を通知する」の多層で運用する。

受け入れ観点

  1. checked-in config から just sentry-alerts-upsert-dry-run が成功し、apply 前に create / update plan が確認できること。
  2. local では sentry user auth だけで just sentry-alerts-list / just sentry-alerts-upsert が動作し、同名 workflow を update / create できること。CI では SENTRY_AUTH_TOKEN を注入した同じ command が動作すること。
  3. root just recipe（list / dry-run / live apply）から operator が迷わず実行できること。
  4. 本件の時点で「AI monitoring は未適用」「OTel exporter は保留」「alerts/workflows は自動化済み」という整理が docs 上で明示されていること。
  5. monitoring runbook に prerequisite / usage / workflow の意味と、他 lane との役割分担が記載されていること。
  6. just sentry-live-config-audit で checked-in workflow plan と live state の drift を確認できること。