suggesting-path-cleaning-rules

パスクリーニングルールの提案

パスクリーニングを設定していないチームは多く、そのため Web 分析の内訳が、ほとんど同じ URL の何千もの断片に分かれてしまいます。この機能では、Web 分析の事前計算コホート向けにクリーニングルールを積極的に提案します。毎週、チームごとに実際のパスをサンプリングし、LLM に {regex, alias} ルールを問い合わせ、チーム固有のパスに対して検証したうえで、レビュー用に保存します。

この機能が行うのは提案のみで、自動適用は行いません。書き換えを適用すると、クリーニング済みのすべてのチャートで過去の数値が変わるため、適用は人が判断します（既存の設定 UI、またはレビュー後に以下の --apply フラグを使用してください）。ルールを手作業で作成する場合や、直接適用する場合は、managing-path-cleaning-rules スキルを使用してください。

アーキテクチャ

• コア: products/web_analytics/backend/path_cleaning_suggestions/service.py
  • sample_pathnames / count_distinct_pathnames — HogQL を使って、ビュー数の多い $pathname を取得します。
  • call_llm_for_rules — LLM ゲートウェイを介した単発の呼び出しです （get_llm_client(product="web_analytics", team_id=...)、モデルは WEB_ANALYTICS_PATH_CLEANING_SUGGESTIONS_MODEL、デフォルトは claude-haiku-4-5）。
  • validate_and_annotate_rules — 各正規表現を re2（ClickHouse の replaceRegexpAll が使用するエンジン）でコンパイルし、サンプルのパスに対して適用テストを行います。コンパイルできないルールや、何も一致しないルールは除外されます。残ったルールには連番の order、match_count、メモリ上の適用前／適用後の examples が付きます（管理コマンドで出力されますが、保存されることはありません。ヘルスイシューのペイロードは health_issue:read だけで読み取れるため、実際のパスを漏らしてはいけません）。これはスキルの「保存前にテストする」手順を自動化したものです。
  • generate_suggestions_for_team — ゲーティングを含めて上記を調整します（以下を参照）。生成のみを行い、保存はしません。
  • apply_suggestions_to_team — ルールを path_cleaning_filters にマージし、上書きはしません（正規表現で重複を除外し、order は続きの値にします）。
• 保存先: path_cleaning_suggestions ヘルスイシュー（HealthIssue、重要度は info）を使用します。専用のモデルはありません。チームごとにアクティブなイシューは 1 件です（hash_keys=[]）。payload には rules、model、sampled_path_count、distinct_path_count が含まれます。適用するか、ルールを手動設定すると、次回のチェック実行時にイシューが解決されます。却下状態はヘルスイシューの dismissed フラグで管理されます。
• スケジュール: PathCleaningSuggestionsCheck （products/web_analytics/backend/temporal/health_checks/path_cleaning_suggestions.py）。共有ヘルスチェックフレームワーク上のヘルスチェックで、毎週実行されます（月曜 06:23 UTC）。対象チームごとに LLM 呼び出しが発生するため、小さなバッチで順次処理します。既存のアクティブな提案があるチームは、新たに LLM を呼び出さずに再出力されます。
• コホート: WEB_ANALYTICS_PATH_CLEANING_SUGGESTIONS_TEAM_IDS。デフォルトは、事前計算の登録リスト WEB_ANALYTICS_LAZY_PRECOMPUTE_TEAM_IDS です。

ゲーティング（チームがスキップされる理由）

generate_suggestions_for_team はステータスを返します。

• skipped_inactive — visited_within_days（デフォルトは 30 日）以内に $pageview を送信していないチームです。Web 分析を積極的に利用しているチームのみを提案対象とします。--ignore-visit-gate で回避できます。
• skipped_configured — チームにパスクリーニングルールがすでに設定されています（include_configured で上書きできます）。
• skipped_low_cardinality — 個別のパスが min_distinct_paths（デフォルトは 50）より少ない状態です。クリーニングしても価値がないため、トークンを消費しません。
• skipped_no_paths — 対象期間内にページビューがありません。
• generated — ルールが生成されました（パスがすでに整理されている場合は空のリストになることがあります。実用的な提案が隠れてしまわないよう、ルールが空の場合は保存しません）。
• error — サンプリングまたは LLM 呼び出しに失敗しました。チームごとに記録し、コホート全体の処理は中断しません。

ユーザーによる提案の確認と適用方法

• 設定バナー：/settings/project#path_cleaning の PathCleaningSuggestionsBanner には、最新の suggested 行が正規表現 → エイリアスのプレビューとして一致件数とともに表示されます。「すべて適用」（プロジェクト管理者のみ）をクリックするとルールが統合され、閉じるボタンをクリックするとバナーが非表示になります。pathCleaningSuggestionsLogic によって制御されます。
• オンボーディングのステップ：OnboardingWebAnalyticsPathCleaningStep（stepKey path_cleaning）では、Web アナリティクスのオンボーディング中に同じバナーが表示されます。
• API（products/web_analytics/backend/api/web_analytics_path_cleaning_suggestions.py）： POST /api/projects/:id/web_analytics_path_cleaning_suggestions/generate/ は、要求に応じて新しい提案を生成して保存します。GET .../{issue_id}/preview/ は、チームで使用頻度の高いパスの最新サンプルにルールを適用し、適用前後のペアを返します（読み取りスコープで、要求に応じて計算され、保存されません。バナーの「パスでプレビュー」モーダルで使用されます）。POST .../{issue_id}/apply/ は、ルールを統合してイシューを解決します（プロジェクト管理者のみ。同じ制限がチーム API の path_cleaning_filters にも適用されます）。 一覧表示と非表示化には、汎用のヘルスイシュー API を使用します （GET /api/projects/:id/health_issues/?kind=path_cleaning_suggestions&status=active&dismissed=false、 PATCH .../health_issues/{id}/ と {"dismissed": true}）。
• ヘルスページ：このチェックは /web/health で他の Web アナリティクスのチェックとともに表示され、人間とエージェント向けの修正方法が案内されます。
• PostHog AI（Max）：生成と適用は、products/web_analytics/mcp/tools.yaml の MCP ツール（web-analytics-path-cleaning-suggestions-{generate,apply}）として公開されているため、ユーザーは Max に自然な会話でパスクリーニングルールの提案と適用を依頼できます。適用は履歴チャートの数値を変更するため destructive であり、MCP の確認ゲートが適用されます。

実行方法

# Default cohort, print suggestions, store health issues:
python manage.py suggest_path_cleaning_rules

# Specific teams, dry run (nothing stored):
python manage.py suggest_path_cleaning_rules --teams 2,19279 --no-store

# Generate AND apply for one reviewed team (merges, never overwrites):
python manage.py suggest_path_cleaning_rules --teams 2 --apply

便利なフラグ：--days（遡る日数）、--limit（サンプリングする上位 N 件のパス）、--min-distinct-paths、--include-configured、--no-store、--apply。

他のヘルスチェックと同様に、ヘルスイシューの refresh エンドポイントまたは管理 UI から、チームごとにこのヘルスチェックを実行することもできます。

提案の確認

チームの有効な提案を読み取ります。

HealthIssue.objects.filter(team_id=team_id, kind="path_cleaning_suggestions", status="active").first()

payload["rules"] の各ルールには、regex、alias、order、reason、match_count が含まれています。適用するかどうかを判断する人に表示するのは、これらの情報です。実際のパスに対する適用前後の例は、生成時に管理コマンドによってのみ出力されます。意図的に、保存されるペイロードには含めていません。

拡張

• 表示チャネル（アプリ内通知、設定バナー、オンボーディングウィザードのステップ）を追加する場合：チームの有効な path_cleaning_suggestions ヘルスイシューを読み取り、その payload["rules"] を表示します。適用は手動のままにしてください。
• モデルを変更する場合：services/llm-gateway/src/llm_gateway/products/config.py で、web_analytics プロダクトの許可リストに追加する必要があります。
• エージェントを使う代替案として、signals-scout-web-analytics-path-cleaning スカウトが設計メモで概要化されています。事前計算対象のコホートには専用ジョブを優先してください。対象のコホートに特化しており、Signals インボックスの調査結果ではなく、構造化され検証済みの行を表示するためです。