コンテンツにスキップ

2026-04 Vendure Sentry Event Policy

背景

Vendure の監視では、これまで Sentry が主に「未処理例外の受け皿」として使われていた。 しかし実際の障害は、以下の 3 種類が混在する。

  1. Node / Nest / GraphQL で未処理に近い例外
  2. アプリが処理継続可能な運用異常
  3. 業務上は失敗だが API としては正常応答になる業務エラー

GraphQL resolver 例外や createAssets のような multipart upload 失敗は、 HTTP 500 や process crash に必ずしも変換されないため、Sentry の自動捕捉だけでは 監視面が不完全になる。

方針

Vendure の Sentry surface は、以下の 3 区分を正本とする。

1. unexpected_exception

  • 予期しない例外
  • 例:
  • resolver / service 内の throw
  • process crash
  • startup 中の未処理例外
  • Sentry 送信:
  • captureException
  • level は error
  • 運用:
  • 原則として issue 化対象

2. operational_failure

  • アプリが検知・処理したが、運用上は異常な状態
  • 例:
  • schema drift 検知
  • startup canary failure
  • drift check 自体の失敗
  • 外形監視の失敗
  • Sentry 送信:
  • captureIssue(... kind: "operational_failure")
  • level は既定で error
  • 同じ語彙で Sentry metric も残す
  • 運用:
  • deploy / startup / infrastructure triage の主対象

3. business_error

  • 業務仕様として返る失敗結果で、HTTP / GraphQL transport は成功する
  • 例:
  • MimeTypeError
  • validation result union
  • permission / precondition failure のうち product 上重要なもの
  • Sentry 送信:
  • captureIssue(... kind: "business_error")
  • level は既定で warning
  • 運用:
  • 全件送信しない
  • 重要導線だけを明示的に対象化する

要件

  1. Vendure の observability helper は、上記 3 区分を API 上で明示できること。
  2. GraphQL resolver 例外は unexpected_exception として Sentry に送ること。
  3. startup canary / schema drift のような handled failure は operational_failure として送ること。
  4. business_error は無差別送信を禁止し、重要導線のみ opt-in で送ること。
  5. event 側の tag は issue_kind を必須とし、triage での検索キーに使えること。
  6. handled failure は、必要に応じて event と metric を同時に残せること。

初期適用範囲

今回の適用対象は以下とする。

  • GraphQL resolver exception capture
  • startup dashboard API canary failure
  • schema drift detected / check failed
  • createAssets の MimeTypeError を business_error として送信
  • order / payment / fulfillment の状態遷移系 mutation の主要 union error を curated allowlist で送信

上記以外の business error は、まず canary / 回帰テストで再発防止を優先し、その上で本番 request path へ段階的に opt-in する。

Inbound noise drop policy (Errors quota 節約)

@ritsubi/utils の sanitizeAndFilterSentryEvent (および React Dashboard の同等関数) は、各サーフェスの beforeSend から呼ばれ、以下のイベントを Sentry に送信する前に drop する。これにより Errors quota を節約しつつ、issue_kind: business_error を持つ curated event は影響を受けない。

  • ブラウザ拡張由来のスタックフレーム / メッセージ (chrome-extension:// 等)
  • Next.js framework control flow (REDIRECT, HTTP_ERROR_FALLBACK_404)
  • 既知ノイズメッセージ: AbortError, Failed to fetch, Load failed, NetworkError when attempting to fetch resource, ResizeObserver loop limit exceeded, ResizeObserver loop completed with undelivered notifications, Non-Error promise rejection captured, The user aborted a request, The operation was aborted
  • bot / 監視 User-Agent (bot, crawler, spider, uptime, healthcheck, monitor, preview の case-insensitive 一致)
  • 期待される HTTP 4xx (400 / 401 / 403 / 404 / 409 / 422) — event.contexts.response.status_code / event.tags.{status_code,statusCode,"http.status_code"} / event.exception.values[*].mechanism.data.status_code のいずれかから判定
  • escape: event.tags.issue_kind === "business_error" の curated event は status に関わらず drop しない

ランダム sampleRate は導入しない (低頻度の重要エラーを失わないため)。staging / preview は production と同じ Sentry project に送信し、environment タグで区別する。

非対象

  • すべての GraphQL errors / union result を自動で Sentry 送信すること
  • すべての validation error を issue 化すること
  • browser / WordPress / Storefront の event policy をこの文書で統合すること

それらは別 surface の要件として個別に管理する。