コンテンツにスキップ

2026-04 staging Sentry diagnostics workflow 要件

位置づけ

staging 環境で実施する Storefront 向け E2E / smoke の失敗時に、GitHub Actions の raw log だけでなく、Sentry 上の issue / event / trace 情報も同じ workflow run から辿れるようにするための追加要件。

本要件は Sentry Logs を二次相関チャネルとして限定採用する。JS runtime（Storefront / Vendure / React Dashboard）では warn / error の console ログ転送と browser failed request capture を有効化する一方、ログの system of record は引き続き GitHub Actions artifact / アプリ側構造化ログとする。Storefront browser は Session Replay を有効とし、React Dashboard browser も admin API 相関付きの Session Replay を有効にして、triage 時に feedback / event / trace を横断できるようにする。Vendure runtime は staging でも Node Profiling を有効化し、slow transaction では Profile タブから CPU profile を辿れるようにする。また Vendure の source map は staging でも CI から artifact upload した sourcemap を正本とし、Fly runtime の source-map 解決は fallback として扱う。

あわせて、triage の初動短縮のため Storefront の Vendure GraphQL 失敗は storefront.graphql_operation / graphql.operation_type / graphql.error_code / http.status_code / dependency.name=vendure を付与し、browser surface（Storefront / React Dashboard）は conservative な beforeSend で browser extension 由来ノイズを除外しつつ、request/context/breadcrumb の sensitive field を redactする。

適用範囲

  • staging-smoke-storefront.yml
  • staging-sentry-smoke-storefront.yml
  • Storefront の non-production debug route
  • /api/debug-sentry
  • /api/client-logs

合意事項

  1. deploy 後レーン
  2. staging-smoke-storefront.yml は引き続き Deploy Staging 成功後に起動する。
  3. safe probe / critical smoke / 既存の real Playwright checks を維持しつつ、failure / cancelled 時に Sentry diagnostics snapshot を回収する。

  4. diagnostics は、少なくとも deployed Storefront release と staging environment をキーに recent issues / events を取得する。

  5. 定期 canary レーン

  6. staging-sentry-smoke-storefront.yml は定期実行と手動実行で起動する。
  7. browser feedback は常設 smoke に載せず、関係者が ?sentry-feedback=1 を付けた manual 確認導線で扱う。
  8. staging 専用の intentional debug event を 1 件発生させる synthetic canary を行う。
  9. synthetic canary の認証は SENTRY_DEBUG_SIGNING_SECRET を元鍵にした marker 束縛の request token を正本とし、他用途の secret を流用しないこと。
  10. SENTRY_DEBUG_TOKEN は非本番の手動疎通確認用に残してよいが、scheduled canaryの認証材料としては扱わないこと。

  11. canary 後に Sentry API から該当 event を取得し、workflow run ごとの相関を確認する。

  12. run marker

  13. synthetic canary は workflow run ごとの marker を持つ。
  14. marker は request header x-sentry-debug-marker または query marker から受け取れるようにする。
  15. Storefront 側は marker を Sentry tag storefront.sentry_debug_marker と context storefront_debug.marker に付与する。

  16. marker は英小文字、数字、.、_、:、- を中心に扱い、長さは 96 文字以内に正規化する。

  17. Sentry diagnostics artifact

  18. diagnostics collector は少なくとも以下を出力する。
    • manifest.json
    • events.json
    • matched-events.json
    • issues.json
    • summary.md
  19. summary.md は GITHUB_STEP_SUMMARY に追記できる形式にする。
  20. 既存の collect-job-attachments で diagnostics bundle を artifact に含める。
  21. diagnostics manifest.json と summary.md には、workflow archive / Playwright manifest と join するための workflowTraceId を含める。

  22. collect-job-attachments の attachment manifest は nested manifest を検出し、 sentry-diagnostics / playwright-artifacts / workflow-archive を列挙できること。

  23. workflow log archive

  24. staging-sentry-smoke-storefront.yml にも workflow-level log archive を追加する。

  25. workflow_run 起点で動いた場合は source_workflow_run_id を保持できるようにする。

  26. release 解決

  27. diagnostics collector が参照する release は GitHub の checkout SHA ではなく、staging に現在配備されている Storefront の /api/version から解決する。

  28. release が欠ける場合は commit から storefront@<commit> を組み立てる。

  29. runtime triage metadata

  30. Storefront の Vendure GraphQL / HTTP failure は、少なくとも storefront.graphql_operation、graphql.operation_type、 graphql.error_code、http.status_code、 dependency.name=vendure を Sentry tag/context に残す。
  31. Storefront の warn/error logger と browser client log は、requestId / route / source を含む breadcrumb 相関を残す。
  32. Storefront / React Dashboard の browser surface は、browser extension 由来ノイズを beforeSend で除外し、token / cookie / authorization などの sensitive field は送信前に redact する。
  33. Storefront browser は Session Replay を有効とし、sample rate は VITE_PUBLIC_SENTRY_REPLAYS_SESSION_SAMPLE_RATE / VITE_PUBLIC_SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE を正本とする。
  34. React Dashboard browser も Session Replay を有効とし、sample rate はコード定数（production: session 10%、non-production: session 100%、on-error 100%）を正本とする。
  35. React Dashboard の admin API request は x-request-id を付与し、browser event / Replay から Vendure 側の request_id, actor_id, actor_type, context dashboard_request, dashboard_admin を辿れること。

  36. Vendure staging runtime は trace sample が 0 より大きいとき Node Profiling を有効化し、slow transaction の Profile タブから CPU profile を参照できること。

  37. Vendure の stack trace は staging でも upload 済み sourcemap を通じて TypeScript の file/line まで遡れること。

受け入れ観点

  1. staging-smoke-storefront.yml が失敗またはキャンセルしたとき、artifact に Sentry diagnostics bundle が含まれること。
  2. staging-sentry-smoke-storefront.yml が定期実行で SENTRY_DEBUG_SIGNING_SECRET から marker 束縛 token を生成して debug event を発生させ、その marker に一致する event を Sentry API から取得できること。
  3. debug route が production では引き続き 404 / 無効であること。
  4. Storefront の Sentry tag / context に storefront.sentry_debug_marker / storefront_debug.marker が含まれること。
  5. monitoring-operations.md と infrastructure-and-environment.md に triage 手順が反映されること。
  6. Storefront の Vendure failure event に graphql.error_code / http.status_code / dependency.name=vendure が含まれること。
  7. Storefront / React Dashboard の browser event が、browser extension 由来ノイズを送信せず、sensitive field を redact すること。
  8. React Dashboard の admin API 起点 event / Replay に request_id, actor_id, actor_type, dashboard_request, dashboard_admin が含まれること。
  9. staging の Vendure slow transaction で Profile タブが利用でき、stack trace が upload 済み sourcemap を通じて TypeScript の file/line まで解決されること。