コンテンツにスキップ

Observability 相関ガイド

概要

Storefront / Vendure / React Dashboard / Playwright / GitHub Actions / Sentry を横断して障害を辿るときは、個別のログや artifact を別々に見るのではなく、同じ相関 ID で join する。

本ドキュメントは、現在の実装で使う識別子、artifact の見方、triage の順序を 1 か所にまとめた正本である。個別 workflow や監視プローブの詳細は 監視・運用設計書 を参照する。

使う識別子

requestId

  • HTTP / GraphQL リクエスト単位の相関 ID。
  • 主に application log、browser log ingest、Sentry breadcrumb の join に使う。
  • Storefront から Vendure へは x-request-id で伝搬する。
  • Playwright 実行時は test identity から決定的に生成し、runtime request と同じ値を使う。

traceId

  • observability 全体で使う trace 単位の ID。
  • traceparent の 32 桁 16 進 trace id を使う。
  • runtime log、Sentry context、Playwright manifest、CI artifact summary を横断するときの主キーとして扱う。
  • requestId と同一視しない。

spanId

  • traceId 配下の span 単位の ID。
  • traceparent の 16 桁 16 進 span id を使う。
  • Playwright から注入された request と、Vendure / Storefront の 1 回の処理を細かく追うときに使う。

workflowTraceId

  • GitHub Actions の workflow run 単位の相関 ID。
  • workflow archive、job attachment、Playwright manifest、Sentry diagnostics bundle を同じ run として join するときに使う。
  • repository, run_id, run_attempt から決定的に生成する。

testCorrelationId

  • Playwright test case 単位の相関 ID。
  • test title, project, retry から決定的に生成する。
  • Playwright manifest の entry と runtime header 注入の seed を一致させるために使う。

伝搬ルール

HTTP headers

  • Storefront inbound:
  • x-request-id
  • traceparent
  • Storefront -> Vendure:
  • x-request-id
  • traceparent
  • browser log ingest:
  • browser logger payload に requestId, traceId, spanId, route, source を含める

runtime surface

  • Storefront server:
  • 構造化ログに requestId, traceId, spanId, surface, source, route を出す
  • Storefront browser:
  • browser logger と /api/client-logs payload に同じ field 名を使う
  • Vendure runtime:
  • Sentry context から observationContext を作り、logger child binding と同じ field 名を使う
  • React Dashboard browser:
  • admin API request と browser event で x-request-id を共有する

構造化ログ contract

現在の構造化ログは、少なくとも以下の field を基準に join する。

  • timestamp
  • service
  • environment
  • surface
  • source
  • message
  • requestId
  • traceId
  • spanId
  • route
  • operationName
  • operationType
  • context
  • error

補足:

  • Vendure logger は message key を正本とし、pino 既定の msg は使わない。
  • Vendure の logger child binding は requestId, traceId, spanId, operationName, operationType, fieldName, apiType, channelId, customerCode, actorType を保持できる。
  • Sentry 側の observationContext と logger binding は同じ vocabulary を使う。

Playwright artifact contract

Playwright artifact の manifest.json には以下を含める。

  • top-level:
  • schemaVersion
  • generatedAt
  • app
  • suite
  • workflowTraceId
  • runId
  • runAttempt
  • entry:
  • app
  • suite
  • project
  • testTitle
  • testCorrelationId
  • requestId
  • traceId
  • spanId
  • retry
  • status
  • workflowTraceId
  • artifacts[]

artifacts[] の kind は以下を使う。

  • trace
  • video
  • screenshot
  • attachment

GitHub Actions artifact chain

workflow 失敗時は、以下の順に辿る。

  1. workflow archive の summary.md で workflowTraceId を確認する。
  2. workflow archive の artifacts.json で attachment artifact を確認する。
  3. job attachment artifact の manifest.json を開き、detectedManifests[] を見る。
  4. detectedManifests[] から nested manifest を選ぶ。
  5. playwright-artifacts
  6. sentry-diagnostics
  7. workflow-archive
  8. Playwright manifest の requestId / traceId / spanId から runtime log と Sentry event を辿る。

失敗時の基本 triage

browser / E2E failure

  1. workflow archive で workflowTraceId を確認する。
  2. job attachment manifest の detectedManifests[] から Playwright artifact を開く。
  3. failure test の entry から requestId / traceId / spanId を取る。
  4. 同じ ID を持つ Storefront / Vendure の構造化ログを見る。
  5. 同じ traceId を持つ Sentry diagnostics / event / replay を見る。

observability chain failure

  1. workflow の Verify observability chain step を確認する。
  2. attachment manifest に playwright-artifacts と sentry-diagnostics が並んでいるか確認する。
  3. nested manifest の workflowTraceId が一致しているか確認する。
  4. Playwright entry に requestId / traceId / spanId が欠けていないか確認する。

どの文書を見るか