vtex-io-observability-and-ops

可観測性と運用準備

このスキルを使用する場面

VTEX IO サービスの本番環境での可視性、トラブルシューティングの動作、または運用上の安全性を改善する必要がある場合に、このスキルを使用します。

• 重要なクライアント呼び出しやフローにメトリクスを追加する
• ルート、ワーカー、インテグレーションのログを改善する
• 運用担当者やサポート担当者に障害を明確に伝える
• サービスが本番環境に対応できる状態か確認する
• レート制限の影響を受けやすいインテグレーションを監視する

次の用途には、このスキルを使用しないでください。

• アプリポリシーの宣言
• 信頼境界のモデリング
• フロントエンドの分析やブラウザーの監視
• ルートコントラクトの設計のみ

判断ルール

• 障害のデバッグに必要な構造化コンテキストを十分に記録します。ただし、秘密情報や機密性の高いペイロードは記録しないでください。
• console.log ではなく、info、warn、error など適切なログレベルを指定した ctx.vtex.logger を使用します。これにより、ログが適切に収集され、VTEX のロギングスタックで検索できるようになります。
• ctx.vtex.logger をプラットフォーム標準のロギング手段として扱います。パートナーが自社のロギングシステムにログを転送する必要がある場合は、各サービス内で VTEX ロガーのパターンを置き換えるのではなく、専用のインテグレーションアプリまたはクライアントを通じて行うことを優先します。
• 重要な下流呼び出しにはクライアントレベルのメトリクスを使用し、ハンドラーレイヤーより下のインテグレーションの動作を可視化します。
• partner-get-order や partner-sync-catalog など、インテグレーションと操作内容を反映したメトリクス名を選び、呼び出し回数、レイテンシ、エラー率を時間の経過に沿って追跡できるようにします。
• 障害が発生した箇所で、その障害を観測できるようにします。ルート、イベント、ワーカーでエラーを黙って握りつぶさないでください。
• レート制限の影響を受けやすい API では、短いタイムアウト、バックオフを考慮したリトライ、頻繁な読み取りのキャッシュを組み合わせて、バースト負荷を軽減し、厳格な制限に達するのを防ぎます。
• リリース前に、高コストまたは不安定なフローで十分な運用シグナルが得られるか確認します。

厳守事項

制約：重要な障害はログ、メトリクス、または永続状態で確認できる必要があります

ルート、イベントハンドラー、ワーカーは、運用担当者から重要な障害を隠してはなりません。

重要な理由

障害が黙って消えてしまうと、実トラフィック下でサービスを診断できなくなり、リトライにも対応できません。

検出方法

エラーを捕捉した後、ログへの記録、メトリクスの出力、明示的な障害状態のいずれも行わずに無視している場合は、作業を中断して障害を明らかにしてください。

正しい例

try {
  await ctx.clients.partnerApi.sendOrder(orderId)
} catch (error) {
  ctx.vtex.logger.error({
    message: 'Failed to send order to partner',
    orderId,
    account: ctx.vtex.account,
    routeId: ctx.vtex.route?.id,
  })
  throw error
}

誤った例

try {
  await ctx.clients.partnerApi.sendOrder(orderId)
} catch (_) {
  return
}

制約：重要なインテグレーション呼び出しにメトリクスを設定する必要があります

運用上重要なクライアント呼び出しには、リクエストの動作を一貫して追跡できるよう、metric を含めるべきです。

重要な理由

メトリクスがないと、インテグレーションの障害やレイテンシのパターンを、一般的なルートの動作から切り分けるのが非常に困難になります。

検出方法

重要な下流インテグレーションの呼び出しに metric がなく、運用上それに依存している場合は、作業を中断して適切なメトリクス名を追加してください。

正しい例

return this.http.get(`/orders/${id}`, {
  metric: 'partner-get-order',
})

誤った例

return this.http.get(`/orders/${id}`)

制約：機密データを漏らさず、ログの有用性を保つ必要があります

ログには本番環境の動作をデバッグするために十分なコンテキストを含める必要がありますが、秘密情報、トークン、不要に機密性の高いペイロードを含めてはなりません。

重要な理由

運用ログに価値があるのは、安全に保持して調査できる場合に限られます。機密情報を記録すると、診断に役立つ保証がないままセキュリティリスクが生じます。

検出方法

ログ行にトークン、認証ヘッダー、個人情報を含む未加工のペイロード、または下流からのレスポンス全体が含まれている場合は、作業を中断してログをサニタイズしてください。

正しい例

ctx.vtex.logger.info({
  message: 'Partner sync started',
  orderId,
  account: ctx.vtex.account,
})

誤った例

ctx.vtex.logger.info({
  message: 'Partner sync started',
  body: ctx.request.body,
  auth: ctx.request.header.authorization,
})

推奨パターン

運用上健全な VTEX IO サービスでは、次のことを行います。

• 重要なクライアント呼び出しでメトリクスを出力し、呼び出し回数、レイテンシ、エラー率を可視化する
• ドメイン ID、アカウント、routeId など、十分な構造化コンテキストを含めて障害をログに記録する
• エラーを黙って握りつぶさない
• ログを記録する前に機密データをサニタイズする
• レート制限の動作を考慮して、リトライ、キャッシュ、スループットを確認する

可観測性は、単にログを増やすのではなく、診断時間を短縮するために活用してください。

よくある障害パターン

• 非同期フローでエラーを捕捉して無視する。
• 本番環境のインシデントを診断するためのコンテキストを十分に記録しない。
• 機密データを記録しすぎる。
• 重要な連携呼び出しのメトリクスを省略する。
• レート制限による失敗を運用上のシグナルではなく、個別のバグとして扱う。

レビューチェックリスト

• 重要な障害は運用担当者が確認できる状態ですか？
• 主要な連携から有用なメトリクスが出力されていますか？
• ログは構造化され、安全ですか？
• リトライ、キャッシュ、レート制限の動作をまとめて考慮していますか？
• オンコール担当者は、利用可能なシグナルからこのフローを診断できますか？

参考資料

• Node クライアントの使用 - メトリクスとリトライに関するクライアントの使用パターン
• レート制限エラーを回避するためのベストプラクティス - 安定した連携のための運用ガイダンス