auditing-endpoints

エンドポイントの監査

このスキルでは、Endpoints プロダクト全体を監査します。未使用のエンドポイント、マテリアライゼーションの失敗、もう誰も呼び出していないマテリアライズ済みバージョンなど、整理すべき対象を見つけたいときに使用します。変更は行わず、レポートを作成します。

エンドポイントごとの詳細な調査には diagnosing-endpoint-performance を使用します。監査の役割は候補を見つけて引き継ぐことです。

このスキルを使用するタイミング

• 「エンドポイントを監査して」／「整理できるエンドポイントはある？」
• プロジェクトを引き継ぐことになり、引き継いだ内容を把握したい
• 定期的なエンドポイントの棚卸し（月次／四半期ごと）
• マテリアライゼーションのコスト予算を超過していて、無効化する対象を把握したい

専用ツールを使うと、エンドポイント単位ですばやく状況を確認できます。呼び出し頻度、直近の利用状況、経時的なコストを確認するには、execute-sql を使って query_log テーブルを問い合わせてください（エンドポイント単位）。バージョンごとの直近の利用状況は endpoint-versions で確認できます。各バージョンには独自の last_executed_at が記録されています。

利用可能なツール

ツール	用途
execute-sql (HogQL)	主な読み取り手段。 メタデータ（name、is_active、current_version、derived_from_insight、last_executed_at）は system.data_modeling_endpoints に、エンドポイント単位の利用状況（呼び出し回数、直近の利用状況、実行時間、バイト数）は query_log に問い合わせます
endpoint-materialization-status	エンドポイントごとに、マテリアライゼーションの対象となるか、現在のステータス、最終実行日時、最後のエラーを確認します（システムテーブルには含まれないため、このツールを使用します）
endpoint-versions	1 つのエンドポイントの全バージョンを新しい順に取得します。各バージョンのクエリ、マテリアライゼーションの状態、last_executed_at が含まれます
endpoint-update	書き込み手段。ユーザーの確認後に無効化（is_active: false）またはマテリアライゼーション解除（is_materialized: false）を行います
agent-feedback	この手順で不足している点やわかりにくい点を PostHog チームに伝え、プロダクトとスキルの改善に役立てます

endpoints-get-all／endpoint-get ツールよりもシステムテーブルからの読み取りを優先してください。SQL クエリを 1 回実行するだけで全エンドポイントの一覧を取得し、メタデータを query_log の利用状況と結合できます。

問題とみなされるもの

カテゴリ	条件	典型的な対応
呼び出しなし	エンドポイントの query_log に行がない（個人用 API キーによる呼び出しのみ）	ユーザーに確認してから無効化する
長期間未使用	query_log で最後の呼び出しが 30 日以上前と記録されている	ユーザーに確認する。多くの場合、安全に無効化できる
非アクティブ	system.data_modeling_endpoints の is_active = 0	意図を確認し、放棄されている場合は削除する
マテリアライズに失敗	endpoint-materialization-status がエラーとともに Failed を返す	diagnosing-endpoint-performance に引き継ぐ
未使用のマテリアライズ済みバージョン	last_executed_at（endpoint-versions から取得）が null、または長期間更新されていないマテリアライズ済みバージョン	そのバージョンをアンマテリアライズするか、より新しいものに切り替える
バージョンのドリフト	多数のバージョンが存在する（クエリが繰り返し変更されている）	履歴上のノイズです。問題ではありませんが、記録しておくとよいでしょう

使用回数に含まれるのは個人用 API キーによる呼び出しのみです。Playground タブまたはアプリからのみ実行されたエンドポイントは、未使用のように見えます。バージョンごとの last_executed_at が記録されるのは、この追跡機能が追加されて以降の実行のみです。そのため、 使用中でもバージョンの値が null になることがあります。削除する前に必ず確認してください。

ワークフロー

1. エンドポイントとメタデータを一覧表示する

execute-sql クエリを 1 つ実行すれば、system.data_modeling_endpoints からすべての情報を取得できます。

SELECT name, is_active, current_version, derived_from_insight, last_executed_at
FROM system.data_modeling_endpoints
ORDER BY name

行がない場合、プロジェクトにエンドポイントはありません。その旨を伝えて終了してください。問題を捏造してはいけません。（ここでの last_executed_at 列は、エンドポイントレベルのタイムスタンプを手軽に確認するためのものです。呼び出し頻度と コストを確認するには、次の手順で query_log を使用してください。）

2. query_log から使用状況を取得する

query_log には、個人用 API キーによる呼び出しがすべて、エンドポイント名とともに記録されます。クエリを 1 つ実行すれば、すべてのエンドポイントの最終呼び出し時期と呼び出し回数を取得できます。

SELECT name, count() AS calls, max(query_start_time) AS last_called
FROM query_log
WHERE endpoint LIKE '%/endpoints/%' AND is_personal_api_key_request
GROUP BY name
ORDER BY name

手順 1 の結果と照合します。

• メタデータにはあるが、query_log にはない → API キー経由で呼び出されたことがない
• 最後の呼び出しが 30 日以上前 → 長期間未使用

query_log には、呼び出しごとの query_duration_ms、read_rows、read_bytes も記録されています。同じ確認作業の中で、 コストの高いエンドポイントを特定するのに役立ちます。これはエンドポイントレベルの情報です。バージョンごとの最終実行時期は endpoint-versions（手順 3）から取得します。

3. マテリアライズの健全性と未使用バージョンを確認する

マテリアライズ済みの各エンドポイントについて、endpoint-materialization-status を呼び出します（これはシステム テーブルにはありません）。status: "Failed" のものは別に提示してください。これらは長期間未使用なのではなく、現在発生している障害です。

次に endpoint-versions を呼び出し、各バージョンの last_executed_at を確認します。last_executed_at が null、または長期間更新されていない マテリアライズ済みバージョンは、未使用のマテリアライズ済みバージョンの候補です。これは手がかりであり、確証ではありません。バージョンごとの最終実行時期として記録されるのは、この追跡機能が追加されて以降の API キーによる実行のみです。アンマテリアライズする前に、ユーザーに確認してください。

4. 監査結果を提示する

カテゴリごとにグループ化し、優先順位を付けたレポートを作成します。生の JSON をそのまま出さず、セクションごとに読みやすい表を使ってください。

## Endpoints audit — 9 issues

### 🔴 Failing materialisations (1)
- weekly_revenue (v3) — Failed 2h ago, "Column 'event_date' does not exist"
  → hand off to diagnosing-endpoint-performance

### 🟠 Never called via API key (3)
- internal_admin_query — created 5 months ago
- legacy_signup_funnel — created 1 year ago, materialised
- experiment_arm_lookup — created 9 months ago

### 🟠 Unused materialised versions (2)  [from endpoint-versions]
- monthly_active_users — v3 materialised, last_executed_at null (currently on v4 — unmaterialise v3)
- order_summary — v1 materialised, last_executed_at null

### 🟡 Stale (3)
- holiday_promo_2024 — last called 4 months ago
- ab_test_phase_1 — last called 2 months ago
- daily_revenue_cohort — last called 45 days ago

Recommended order:
1. Investigate the failing materialisation (blocks fresh data)
2. Unmaterialise the unused versions (free storage + compute)
3. Disable the never-called endpoints (if user confirms)
4. Review stale endpoints with the user

正確な形式よりも、優先順位が付いていること、グループ化されていること、実行可能な内容であること、引き継ぎ先が明確であることが重要です。

5. 次のステップを提示する

判断を示すのではなく、明確な質問で締めくくります。

• 「使われていないバージョンのマテリアライズを解除しますか？」 — バージョンごとに is_materialized: false を指定して endpoint-update を実行する必要があります
• 「一度も呼び出されていないエンドポイントを無効にしますか？」 — is_active: false を指定して endpoint-update を実行する必要があります
• 「マテリアライズに失敗している原因を調べますか？」 — diagnosing-endpoint-performance に引き継ぎます

監査だけを根拠に操作してはいけません。 無効化やマテリアライズの解除は外部 API の利用者に影響するため、 変更を加える前に必ず確認してください。

やり取りの例

User: "Audit my endpoints"

Agent steps:
- execute-sql on system.data_modeling_endpoints → 12 endpoints (4 materialised)
- execute-sql on query_log grouped by name → 8 endpoints have calls
- endpoint-materialization-status on each materialised endpoint → 1 failing
- endpoint-versions on the materialised ones → order_summary v2's last_executed_at is null

- Report:
  "Found 6 things worth looking at across 12 endpoints:

   🔴 Failing materialisations (1)
   - monthly_active_users (v2) — materialisation failed yesterday with
     'memory limit exceeded'. The endpoint is still callable inline but
     responses will be slower.

   🟠 Never called via API key (3)
   - legacy_funnel_v1 — created 11 months ago
   - test_export — created 3 months ago
   - admin_dump — created 8 months ago, materialised (wasteful)

   🟠 Unused materialised versions (1)  [from endpoint-versions]
   - order_summary v2 — materialised but its last_executed_at is null
     while v3 is current. Likely safe to unmaterialise v2.

   🟡 Stale (1)
   - holiday_2024 — last called 5 months ago

   Caveat: usage only counts personal-API-key calls; playground and
   dashboard runs aren't counted. Per-version recency comes from
   endpoint-versions and is sparse. Confirm before disabling.

   Want me to start with the failing materialisation, or clean up the
   unused version first?"

重要な注意事項

• 監査は読み取り専用です。 このフローでは破壊的なツールを呼び出してはいけません。変更する前に、引き継ぐか確認してください。
• 空の結果は健全な状態です。 理論上の問題を挙げて、空のレポートを埋める必要はありません。「整理するものはありません」という回答で問題ありません。
• SQL で読み取り、バージョンツールで詳細を確認します。 system.data_modeling_endpoints（メタデータ）と query_log（エンドポイント単位の呼び出し数、最終呼び出し時期、コスト）を execute-sql 経由で確認すれば、監査の大半に回答できます。バージョンごとの最終呼び出し時期は endpoint-versions（各バージョンの last_executed_at）から取得します。
• 対象は API キーによる呼び出しのみです。 使用状況に含まれるのは、個人 API キーによる呼び出しだけです。Playground タブまたはアプリからのみ使用されたエンドポイントは、未使用のように見えます。操作する前に必ず確認してください。
• マテリアライズにはストレージとコンピューティングのコストがかかります。 エンドポイントのマテリアライズが不要になった場合、最も低コストな対処は、エンドポイントを削除することではなく、is_materialized: false を指定して endpoint-update を実行することです。
• 非アクティブであることと、古くなっていることは別です。 is_active: false のエンドポイントは、意図的に無効化されています。ユーザーが本当に不要だと確認しない限り、削除を推奨してはいけません。