o11y-logging

JoelClaw のオブザーバビリティとログ記録

デフォルトでサイレント障害を防ぎます。オブザーバビリティは任意の仕上げではなく、完了に不可欠な要素です。

必須ルール

1. 正式なイベント契約のみを使用します。
   • packages/system-bus/src/observability/otel-event.ts
   • packages/system-bus/src/observability/emit.ts
   • packages/system-bus/src/observability/store.ts
2. Worker／Inngest のコードは、emitOtelEvent または emitMeasuredOtelEvent を通じてイベントを出力します。
3. Gateway のコードは、emitGatewayOtel を通じてイベントを出力します。
4. 内部での取り込みには、アドホックな書き込みではなく、POST /observability/emit（packages/system-bus/src/serve.ts）を使用します。
5. console.log を主要なオブザーバビリティ手段として扱ってはいけません。構造化イベントを信頼できる唯一の情報源として維持します。
6. カーディナリティの高い値は、ファセットフィールド（source、component、level、success）ではなく、metadata に格納します。
7. 失敗時は、意味のある error とともに success: false を設定します。
8. 現在のテレメトリ設定で必要なシンクへの配信を確認します。まずミラーが有効かどうかを調べます。廃止済みまたは任意のミラーは、無関係な作業の妨げにはなりません。
9. Inngest の耐久関数では、「一度だけ出力する」テレメトリは必ず step.run(...) 内に置き、再開後のリプレイによる重複を防ぎます。

イベントの規約

• source：サブシステム（worker、gateway、webhook、memory、verification など）
• component：安定したモジュール／サービス名（check-system-health、redis-channel、observe）
• action：安定したドット区切りのアクション（system.health.checked、events.immediate_telegram）
• metadata：リクエスト ID、デプロイ ID、関数 ID、セッション ID、ペイロード識別子
• duration_ms：時間を計測する操作には含めます

イベントごとに、幅広いコンテキストを持つイベントを各主要な境界／操作で 1 つ出力します。文字列ログをあちこちに散在させる方式は使いません。

実装ワークフロー

1. 変更対象の境界を特定します。
   • Inngest 関数、gateway チャネル、webhook ルート、API ルート、バックグラウンドジョブ、同期ステップ。
2. 成功時と失敗時のエンベロープを追加します。
   • 長時間のタスクでは開始時と完了時、短時間のタスクでは完了時に 1 つのイベントを出力します。
3. 運用上およびビジネス上のコンテキストを metadata に含めます。
   • 例：関数 ID、イベント ID、プロバイダー、キューの深さ、影響を受けるリソース ID。
4. 重大度は適切に設定します。
   • 通常の動作には debug/info、復旧可能な劣化には warn、失敗には error/fatal を使用します。
5. 完了前に検証ゲートを実行します。

チェックリストとコマンドの詳細については、references/implementation-checklist.md を参照してください。

クイックパターン

Worker／Inngest の時間計測対象の操作

import { emitMeasuredOtelEvent } from "../../observability/emit";

await emitMeasuredOtelEvent(
  {
    level: "info",
    source: "worker",
    component: "content-sync",
    action: "content_sync.run",
    metadata: { trigger: event.name },
  },
  async () => {
    await runSync();
  }
);

Gateway からのイベント出力

import { emitGatewayOtel } from "../observability";

await emitGatewayOtel({
  level: "error",
  component: "redis-channel",
  action: "events.immediate_telegram",
  success: false,
  error: "telegram_send_failed",
  metadata: { sessionId, queueDepth },
});

CLI からのイベント出力

JSON コンテキストには --metadata を使用します。--attributes フラグはありません。

joelclaw otel emit "task.completed" \
  --source system \
  --component skills \
  --success true \
  --metadata '{"session":"NimbleBadger","task":"install wzrrd-publish skill"}'

完了の定義

• 変更したパスに構造化 OTEL イベントが追加されている。
• オブザーバビリティデータを Typesense／Convex に直接書き込む、機能レベルの処理がない。
• スモークプローブが成功する（scripts/otel-smoke.sh）。
• joelclaw otel list と joelclaw otel stats が想定どおりの動作を示す。
• 新たな失敗モードを source、component、action で検索できる。

Inngest のリプレイとハングのトリアージ

ステップのコードが実行されているように見えるにもかかわらず、実行が RUNNING／CANCELLED のまま Finalization エラーになる場合に使用します。

1. まず実行トレースを調べます。

joelclaw run <run-id>

errors.Finalization.stack に Unable to reach SDK URL が含まれているか確認します。

2. 実際のネットワーク到達性の問題か、Worker 側のブロックかを確認します。

joelclaw inngest status
joelclaw logs worker --lines 200
joelclaw logs errors --lines 200

3. OTEL のリプレイノイズを確認します。

一度だけ出力されるはずのアクション（例：manifest.archive.prereqs-passed）が 1 回の実行ウィンドウ内に数百回現れる場合は、そのイベント出力を独立した step.run 内に移します。

joelclaw otel search "manifest.archive.prereqs-passed" --hours 1

4. Unable to reach SDK URL は、原因を特定できない症状として扱います。

イングレスの問題を示す場合もありますが、実際には、関数ハンドラーがローカル I/O や依存関係の処理で長時間ブロックし、ファイナライズが完了できない場合にも発生します。

ヘルパースクリプト

すばやくエンドツーエンドのプローブを行うには、scripts/otel-smoke.sh を使用します。

./skills/o11y-logging/scripts/otel-smoke.sh verification o11y-skill probe.emit

Key Files

• packages/system-bus/src/observability/otel-event.ts
• packages/system-bus/src/observability/emit.ts
• packages/system-bus/src/observability/store.ts
• packages/system-bus/src/serve.ts
• packages/gateway/src/observability.ts
• packages/system-bus/src/inngest/functions/check-system-health.ts
• packages/cli/src/commands/otel.ts
• apps/web/app/api/otel/route.ts