オブザーバビリティのセットアップ

アクションが失敗したときに役立つ情報を見つける

可観測性とは、アプリが何をしたかを確認することを意味します。 Web サーバーを実行している端末から始めます。失敗したアクションを 1 つ繰り返し、最初のエラーと相関 ID (同じリクエストからのメッセージをリンクするラベル) を読み取ります。助けを求めるときは、コマンド、時刻、サニタイズされたエラーを共有してください。 .env ファイルやトークンを共有しないでください。

ホストされたエラー レポートの場合は、「健全性と操作」に従って、apps/web/.env.local またはホストの環境ダッシュボードでサポートされている監視設定を構成します。保存してサーバーを再起動します。テスト環境で制御されたテストの失敗をトリガーし、それが正しいワークスペース コンテキストで表示されることを確認します。設定されている監視は、イベントを受信したことを証明するものではありません。

ALERT_WEBHOOK_URL は、ジョブおよび端末 Webhook 配信失敗アラートのオプションの HTTPS 宛先です。必要な場合は、互換性のある受信エンドポイントを作成し、その URL をサーバー側に保存します。それ以外の場合は空のままにしてください。エージェントに、1 つの障害をシミュレートし、テキストに秘密を含めずに 1 つのアラートだけを確認するよう依頼します。このテストでは、顧客アカウントで有償作業や失敗をトリガーしないでください。

• アプリケーションの正常性と動作設定を確認する
• ローカル端末のエラーを診断

ワークスペース単位の監査証跡を保つ

監査レコードは、ワークスペース内のプロバイダー設定更新のような変更を捕捉します。それらのレコードを読み書きする前に認証済みワークスペースを解決し、製品固有のイベントを追加するときその境界を維持します。

アクションとそれを理解するのに必要な識別子を記録します。プロバイダー認証情報やその他の機密値は監査ペイロードやログの外に保つべきです。

製品イベントを捕捉する

オブザーバビリティパッケージは AnalyticsClient アダプターとワークスペーススコープの AnalyticsEvent 値を公開します。各イベントは名前、distinct ID、workspaceId、オプションのプロパティを運びます。

createObservability を使って設定済みの分析クライアント経由でイベントをルーティングします。構造化プロパティは配信前にサニタイズされます。機密な自由記述テキストもイベント名やプロパティ値から外してください。

安全なコンテキストでエラーを報告する

ErrorClient は workspaceId タグと構造化された追加コンテキスト付きで例外を捕捉します。共有オブザーバビリティ層は、設定済みクライアントへ転送する前に例外と機密コンテキストをサニタイズします。

ローカルアダプターを使って、監視プロバイダーを呼ばずに捕捉されたイベントと例外を検証します。外部送信先を有効にする前に、ワークスペースタグが残り認証情報が除去されることをテストします。

タスク、ジョブ、Webhook 全体でリクエストを追跡します

エントリ境界は、元のリクエストをそれがトリガーする作業にリンクする corr_<uuid> 相関 ID を作成します。 AI タスクの送信では、タスク ペイロードと ai_task_submitted イベントに ID がスタンプされ、各請求 Webhook 受信者はリクエストごとに 1 つを作成し、スケジューラーはディスパッチされたジョブごとに 1 つを作成します。

同じ ID が、job.completed および ai_task_completed イベント プロパティ、captureException エクストラ、webhook_event レジャー ペイロード、および各 webhook_delivery ペイロード メタに影響を与えるため、サブスクライバーが受け取る署名付き本文内に配置されます。 ID の欠落または不正な形式は許容されます。コンシューマーは古い行を拒否する代わりに、新しい ID を作成します。

実際の障害に関するアラート

ALERT_WEBHOOK_URL を、JSON POST 形式の {text, name, severity, context}; を受け入れる任意の HTTPS エンドポイントに設定します。 Slack スタイルの受信 Webhook はそのまま機能します。アラートは 5 秒のタイムアウトを持つファイア アンド フォーゲットで、配信が失敗すると 1 つのコンソール警告がログに記録され、変数が設定されていない間はアラートが停止します。

出荷されるアラートは、job.failed (警告 - ジョブ ハンドラーがスローしたか、ジョブ タイプが不明) と webhook.delivery_failed (クリティカル - 送信配信が最後の試行後にターミナル障害に達した場合のみ。通常の再試行は行われず、各配信行で最大 1 回アラートが生成されます) です。

期間を測定し、構造化されたログをストリーミングする

serverObservability.measure は、元のエラーをマスクすることなく、非同期操作の時間を計測し、成功時と失敗時に、durationMs を伴う <name>.duration 分析イベントを発行します。 ai.task.execute ジョブの実行はすでにラップされているため、タスクの実行期間は構成された分析クライアント内に収まります。

serverObservability.logger は、レコードごとに JSON 行を環境フィールドとサービス ベース フィールドとともに stdout に書き込みます。共有編集レイヤーは、行が出力される前にシークレットを削除します。

インストールとセットアップ

1. エラーレポートには SENTRY_DSN を設定します——例外は相関 ID とワークスペースタグ付きで捕捉されます。

2. プロダクト分析には NEXT_PUBLIC_POSTHOG_KEY と NEXT_PUBLIC_POSTHOG_HOST を設定します——これらは設計上公開されるブラウザ向けの値です。

3. 障害アラートには ALERT_WEBHOOK_URL を Slack 互換エンドポイントに設定します——アプリは {text, name, severity, context} の JSON を POST します。

SENTRY_DSN=https://…@….ingest.sentry.io/…

NEXT_PUBLIC_POSTHOG_KEY=phc_…
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

ANALYTICS_PROVIDER=off    # off | local | plausible | posthog
# ANALYTICS_SITE_ID=
# ANALYTICS_HOST=

ALERT_WEBHOOK_URL=https://hooks.slack.com/services/…

実装ワークフロー

オブザーバビリティ層は転送前に例外をサニタイズし既知のシークレットキーをマスクします——ただし自由形式のイベントテキストは作者の責任です。認証情報はイベント名やプロパティ値に入れないでください。

ローカルアダプターにより、テストは Sentry や PostHog を呼ばずに捕捉されたイベントと例外をアサートできます；これらの変数はローカル実行には不要です。

シグナルは流れていますか？「カスタムドメインのセットアップ」に進みます。

検証とトラブルシューティング

テスト例外を発火し、ペイロードからシークレットが除かれた状態で Sentry に届くことを確認し、次に配線された障害が ALERT_WEBHOOK_URL に POST されることを確認します。イベントが届かない場合は、DSN/キーのペアと、サーバーからホストへ到達可能であることを確認してください。