Suggérer des règles de nettoyage de chemins

De nombreuses équipes ne configurent jamais le nettoyage de chemins, ce qui fragmente leurs analyses web sur des milliers d'URLs quasi identiques. Cette fonctionnalité suggère proactivement des règles de nettoyage pour la cohorte de précompute d'analyse web : chaque semaine, pour chaque équipe, elle échantillonne les chemins réels, demande à l'LLM des règles {regex, alias}, les valide par rapport aux chemins de l'équipe, et les stocke pour examen.

Elle ne suggère que — elle n'applique jamais automatiquement. L'application de réécritures modifie les nombres historiques dans chaque graphique nettoyé, ce qui reste une décision humaine (l'interface de paramètres existante, ou le flag --apply ci-dessous après examen). Pour créer ou appliquer directement des règles, utilisez la skill managing-path-cleaning-rules.

Architecture

• Core : products/web_analytics/backend/path_cleaning_suggestions/service.py
  • sample_pathnames / count_distinct_pathnames — top $pathname par vues via HogQL.
  • call_llm_for_rules — appel unique via la passerelle LLM (get_llm_client(product="web_analytics", team_id=...), modèle WEB_ANALYTICS_PATH_CLEANING_SUGGESTIONS_MODEL, défaut claude-haiku-4-5).
  • validate_and_annotate_rules — compile chaque regex avec re2 (moteur utilisé par replaceRegexpAll de ClickHouse) et applique le test aux chemins échantillonnés. Les règles qui ne compilent pas ou ne correspondent à rien sont supprimées ; les survivantes obtiennent un order dense, un match_count, et des examples avant/après en mémoire (imprimés par la commande de gestion, jamais stockés — les payloads d'enjeux de santé sont lisibles avec juste health_issue:read et ne doivent pas divulguer les chemins réels). C'est l'étape « test avant sauvegarde » de la skill, automatisée.
  • generate_suggestions_for_team — orchestre ce qui précède avec gardiennage (voir ci-dessous) ; génération pure, pas de stockage.
  • apply_suggestions_to_team — fusionne les règles dans path_cleaning_filters, ne remplace jamais (déduplique par regex, continue order).
• Stockage : un enjeu de santé path_cleaning_suggestions health issue (HealthIssue, sévérité info) — pas de modèle dédié. Un enjeu actif par équipe (hash_keys=[]) ; le payload contient rules, model, sampled_path_count, distinct_path_count. L'application (ou la configuration manuelle de règles) résout l'enjeu à la prochaine exécution du contrôle ; le rejet est le flag dismissed du health-issue.
• Planification : PathCleaningSuggestionsCheck (products/web_analytics/backend/temporal/health_checks/path_cleaning_suggestions.py), un contrôle de santé sur le framework partagé de contrôles de santé, hebdomadaire (lun 06:23 UTC), petits lots séquentiels car chaque équipe admissible coûte un appel LLM. Les équipes ayant une suggestion active existante sont réémises sans nouveau trajet LLM.
• Cohorte : WEB_ANALYTICS_PATH_CLEANING_SUGGESTIONS_TEAM_IDS, par défaut la liste d'inscription de précompute WEB_ANALYTICS_LAZY_PRECOMPUTE_TEAM_IDS.

Gardiennage (pourquoi une équipe est ignorée)

generate_suggestions_for_team retourne un statut :

• skipped_inactive — l'équipe n'a envoyé aucun $pageview dans les visited_within_days (défaut 30) ; nous ne suggérons que pour les équipes utilisant activement l'analyse web. Contourner avec --ignore-visit-gate.
• skipped_configured — l'équipe a déjà des règles de nettoyage de chemins (remplacer avec include_configured).
• skipped_low_cardinality — moins de chemins distincts que min_distinct_paths (défaut 50) ; le nettoyage n'ajoute pas de valeur, nous n'utilisons pas de tokens.
• skipped_no_paths — aucun pageview dans la fenêtre.
• generated — règles produites (peut être une liste vide si les chemins sont déjà propres ; les générations vides ne sont jamais stockées, elles ne peuvent donc pas masquer une suggestion exploitable).
• error — échantillonnage/LLM échoué ; capturé par équipe, n'interrompt jamais le balayage de cohorte.

Comment les utilisateurs voient et appliquent les suggestions

• Bannière de paramètres : PathCleaningSuggestionsBanner sur /settings/project#path_cleaning affiche la dernière ligne suggested sous forme d'aperçus regex → alias avec des nombres de correspondances ; « Appliquer tout » (admins de projet uniquement) fusionne les règles, le bouton fermer rejette. Piloté par pathCleaningSuggestionsLogic.
• Étape d'intégration : OnboardingWebAnalyticsPathCleaningStep (stepKey path_cleaning) affiche la même bannière lors de l'intégration d'analyse web.
• API (products/web_analytics/backend/api/web_analytics_path_cleaning_suggestions.py) : POST /api/projects/:id/web_analytics_path_cleaning_suggestions/generate/ produit et stocke une suggestion nouvelle à la demande ; GET .../{issue_id}/preview/ applique les règles à un nouvel échantillon des chemins principaux de l'équipe et retourne des paires avant/après (portée de lecture, calculée à la demande, jamais stockée — cela sauvegarde la modale « Aperçu sur vos chemins » de la bannière) ; POST .../{issue_id}/apply/ fusionne les règles et résout l'enjeu (admin de projet uniquement — la même porte que l'API d'équipe met sur path_cleaning_filters). L'énumération et le rejet passent par l'API des health-issues générique (GET /api/projects/:id/health_issues/?kind=path_cleaning_suggestions&status=active&dismissed=false, PATCH .../health_issues/{id}/ avec {"dismissed": true}).
• Page de santé : le contrôle s'affiche sur /web/health aux côtés des autres contrôles d'analyse web, avec des conseils de correction pour les humains et les agents.
• PostHog AI (Max) : la génération/application sont exposées comme outils MCP dans products/web_analytics/mcp/tools.yaml (web-analytics-path-cleaning-suggestions-{generate,apply}), afin qu'un utilisateur puisse demander à Max de suggérer des règles de nettoyage de chemins et les appliquer de façon conversationnelle. L'application est destructive (elle change les nombres de graphiques historiques), donc la porte de confirmation MCP s'applique.

L'exécuter

# Cohorte par défaut, imprimer les suggestions, stocker les enjeux de santé :
python manage.py suggest_path_cleaning_rules

# Équipes spécifiques, exécution sèche (rien stocké) :
python manage.py suggest_path_cleaning_rules --teams 2,19279 --no-store

# Générer ET appliquer pour une équipe examinée (fusionne, ne remplace jamais) :
python manage.py suggest_path_cleaning_rules --teams 2 --apply

Flags utiles : --days (lookback), --limit (top-N chemins échantillonnés), --min-distinct-paths, --include-configured, --no-store, --apply.

Le contrôle de santé peut également être déclenché par équipe à partir du point de terminaison refresh des health-issues ou de l'interface d'administration, comme n'importe quel autre contrôle de santé.

Examiner les suggestions

Lire une suggestion active d'une équipe :

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

Chaque règle dans payload["rules"] contient regex, alias, order, reason, et match_count — c'est ce qu'il faut montrer à un humain décidant d'appliquer. Les exemples avant/après sur les chemins réels ne sont imprimés que par la commande de gestion au moment de la génération ; ils sont délibérément tenus hors du payload stocké.

Étendre

• Ajouter un canal de surfaçage (notification in-app, bannière de paramètres, étape d'assistant d'intégration) : lisez le health-issue path_cleaning_suggestions actif de l'équipe et affichez son payload["rules"]. Gardez l'application manuelle.
• Changer le modèle : il doit être autorisé pour le produit web_analytics dans services/llm-gateway/src/llm_gateway/products/config.py.
• L'alternative agentique — un scout signals-scout-web-analytics-path-cleaning — est esquissée dans les notes de conception ; préférez le job dédié pour la cohorte de précompute car il cible exactement cette cohorte et affiche des lignes structurées et validées plutôt que des résultats de boîte de réception Signals.