exploring-endpoint-execution-logs

エンドポイント実行ログの確認

各エンドポイントの実行時に、PostHog の log_entries ストアへ実行ログが 1 件出力されます。このスキルでは、特定のエンドポイントのログエントリを読み取り、「実行時に何が起きたか？」を確認できます。これは、設定と query_log からキャッシュ／マテリアライズ戦略を判断する diagnosing-endpoint-performance に対する、ログレベルでの補完機能です。

このスキルを使う場面

• 「エンドポイントが失敗する／エラーになるのはなぜですか？」
• 「エンドポイント X のログ／最近の実行を見せてください」
• 「直近の実行ではキャッシュが使われましたか？ 何行返されましたか？」
• 「エンドポイント Y の前回の実行時に何が起きましたか？」

「このエンドポイントは遅いのですが、何を変更すればよいですか？」という質問には、 diagnosing-endpoint-performance を使ってください。プロジェクト全体に関する質問（「整理できるものはありますか？」）には、 auditing-endpoints を使ってください。

実行ログエントリの形式

各実行につき、エントリが 1 件だけ生成されます。成功時のレベルは INFO、失敗時は ERROR です。メッセージには、検索可能な key=value トークンとして追加データが含まれます。

Endpoint executed · path=materialized cache=hit duration_ms=142 rows=1024 version=3
Endpoint execution failed · path=inline error=ResolutionError version=3

トークンの意味：

トークン	値	意味
path	materialized / inline / ducklake / ducklake_fallback	実行された経路
cache	hit / miss	クエリ結果キャッシュが使われたか（ducklake の場合は省略）
duration_ms	integer	実行にかかった実時間
rows	integer	返された結果の行数
version	integer	実行されたエンドポイントのバージョン
error	例：ResolutionError、HogVMException	エラークラス／HogQL コード名（失敗時のみ）

実行ごとに異なる instance_id が付与されるため、ビューアーではログを実行単位でグループ化できます。

利用可能なツール

ツール	用途
endpoint-logs	主なツール。名前で指定した 1 つのエンドポイントの実行ログエントリを取得します。レベル、検索語、時間範囲、instance_id で絞り込めます。limit は最大 500 です。
endpoint-get	コンテキスト確認用のエンドポイント設定（現在のバージョン、マテリアライズ、クエリ種別）
execute-sql	代替手段。log_entries（log_source='endpoints'）を直接対象に集計します

絞り込み

endpoint-logs では、標準のログフィルターを利用できます。

• level — カンマ区切りで指定します。例：失敗した実行のみを表示する場合は ERROR、すべて表示する場合は INFO,ERROR。
• search — メッセージ内の大文字と小文字を区別しない部分文字列検索です。追加データは key=value トークン形式のため、cache=miss、path=inline、error=ResolutionError、または特定の version=3 を検索できます。
• after / before — 時間範囲を指定する ISO タイムスタンプです。
• instance_id — 特定の実行を指定します。
• limit — 1～500（デフォルトは 50）です。

ワークフロー

1. 名前でエンドポイントを特定します。URL が指定されている場合は、 /api/projects/{team_id}/endpoints/{name}/run から解析します。

2. まず広く確認します。エンドポイントの最近の期間を指定して endpoint-logs を実行し、レベルとトークンに目を通します。

3. 症状に合わせて絞り込みます。

   • 失敗の場合 → level=ERROR を指定し、error= トークンと path= を確認して、どこで問題が発生したかを把握します。
   • キャッシュに関する懸念の場合 → search=cache=miss を指定し、実行でキャッシュがミスする頻度を確認します。
   • 結果が誤っている場合 → 実行間で rows= を比較し、version= を確認して、バージョン更新後にリグレッションが発生していないかを調べます。

4. 多数の実行にわたる件数や傾向（例：1 週間のエラー率）を調べるには、log_entries に対して execute-sql を使います。

   SELECT toDate(timestamp) AS day, upper(level) AS level, count() AS runs
   FROM log_entries
   WHERE log_source = 'endpoints' AND log_source_id = '<endpoint_uuid>'
   GROUP BY day, level ORDER BY day DESC
   

   endpoint-get からエンドポイントの UUID を取得します（log_source_id はエンドポイント名ではなく、エンドポイント ID です）。

5. 何が、いつから、どのバージョン／パスで失敗しているのか、また設定の問題なのか（diagnosing-endpoint-performance に引き継ぎます）、クエリのバグなのかをまとめます。

やり取りの例

User: "weekly_signups started erroring this morning"

Agent steps:
- endpoint-logs weekly_signups, level=ERROR, after=<this morning>
  → several "Endpoint execution failed · path=inline error=ResolutionError version=5"
- endpoint-get weekly_signups → current version is v5 (bumped today)
- endpoint-logs weekly_signups, level=INFO, before=<this morning>
  → prior runs: "path=inline cache=hit ... version=4" succeeded

- "v5 (created this morning) is failing with a ResolutionError on the inline path — it can't
   resolve a table or field reference. v4 ran fine. This looks like a bad query in the new
   version. Want me to pull the v5 query (endpoint-versions) so we can fix it, or roll back to v4?"

重要な注意事項

• 実行ごとに 1 件です。 ステップごとのトレースはありません。エンドポイントは完了を示す行を 1 行だけ記録します。詳細は複数行ではなく、トークンに含まれています。
• log_source_id はエンドポイントの UUID です。 エンドポイント名ではありません。execute-sql を使う場合は、先に endpoint-get で取得します。
• ログの保持期間は約 90 日（log_entries の TTL）です。それより古い実行は表示されません。
• 実行ログ ≠ クエリのパフォーマンスです。 endpoint-logs では、何が起きたか、実行がなぜ失敗したかが分かります。「マテリアライズすべきか／キャッシュ TTL を延長すべきか」を判断するには、設定と query_log のコスト指標を分析する diagnosing-endpoint-performance を使います。
• ログ出力はベストエフォートです。 各実行後にログ行が出力されますが、実行がブロックされることはありません。呼び出し元では実行が成功したのにログが見つからない場合は、クエリではなくログ出力が破棄されたことを意味します。