Audit des endpoints

Cette skill produit un audit à l'échelle du projet du produit Endpoints. Utilisez-la quand l'utilisateur veut identifier ce qui nettoyer — endpoints inutilisés, matérialisations défaillantes, versions matérialisées que personne n'appelle plus. Elle ne modifie rien ; elle rapporte.

L'investigation plus approfondie par endpoint est diagnosing-endpoint-performance. Le rôle de l'audit est de trouver des candidats et de les transmettre.

Quand utiliser cette skill

• « Audit mes endpoints » / « Quels endpoints puis-je nettoyer ? »
• L'utilisateur reprend un projet et veut savoir ce qu'il a hérité
• Un examen périodique (mensuel / trimestriel) de la prolifération d'endpoints
• L'utilisateur a dépassé son budget de coûts de matérialisation et veut savoir quoi désactiver

Les outils dédiés offrent une vue rapide au niveau de l'endpoint. Pour la fréquence d'appel, la récence et le coût dans le temps, interrogez la table query_log avec execute-sql (niveau endpoint). La récence par version provient de endpoint-versions — chaque version porte son propre last_executed_at.

Outils disponibles

Préférez la lecture depuis les tables système plutôt que les outils endpoints-get-all / endpoint-get — une seule requête SQL retourne l'inventaire complet et vous permet de joindre les métadonnées à l'utilisation dans query_log.

Qu'est-ce qui compte comme un problème

Les comptages d'utilisation concernent uniquement les appels en clé API personnelle — un endpoint exercé uniquement depuis l'onglet Playground ou l'app ressemblera à inutilisé. Le last_executed_at par version n'est enregistré que pour les exécutions depuis l'ajout de ce suivi, donc une version peut afficher null tout en étant utilisée ; confirmez toujours avant de supprimer.

Workflow

1. Lister les endpoints et leurs métadonnées

Une seule requête execute-sql récupère l'inventaire complet depuis system.data_modeling_endpoints :

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

Aucune ligne → le projet n'a pas d'endpoints ; dites-le et arrêtez. N'inventez pas de problèmes. (La colonne last_executed_at ici est un timestamp de commodité au niveau endpoint ; pour la fréquence d'appel et le coût, utilisez query_log à l'étape suivante.)

2. Extraire l'utilisation depuis query_log

query_log enregistre chaque appel en clé API personnelle, identifié avec le nom de l'endpoint. Une requête donne la récence et les compteurs d'appels sur tous les endpoints :

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

Croisez avec l'étape 1 :

• Dans les métadonnées, absent de query_log → jamais appelé via clé API
• Dernier appel plus de 30 jours ago → obsolète

query_log expose aussi query_duration_ms, read_rows, et read_bytes par appel — utile pour signaler les endpoints coûteux dans le même passage. C'est au niveau endpoint ; la récence par version provient de endpoint-versions (étape 3).

3. Vérifier la santé de la matérialisation et les versions inutilisées

Pour chaque endpoint matérialisé, appelez endpoint-materialization-status (ce n'est pas dans les tables système). Mettez en avant ceux avec status: "Failed" séparément — ce sont des défaillances actives, pas de l'obsolescence.

Appelez ensuite endpoint-versions et lisez le last_executed_at de chaque version : une version matérialisée qui est null ou ancien est un candidat de version-matérialisée-inutilisée. Traitez ceci comme une piste, pas une preuve — la récence par version compte uniquement les exécutions en clé API depuis l'ajout du suivi, donc confirmez avec l'utilisateur avant de dématérialiser.

4. Présenter l'audit

Proposez un rapport priorisé groupé par catégorie. Ne videz pas du JSON brut ; utilisez un tableau lisible par section :

## Audit des endpoints — 9 problèmes

### 🔴 Matérialisations défaillantes (1)
- weekly_revenue (v3) — Défaillance il y a 2h, « Column 'event_date' does not exist »
  → transmettre à diagnosing-endpoint-performance

### 🟠 Jamais appelé via clé API (3)
- internal_admin_query — créé il y a 5 mois
- legacy_signup_funnel — créé il y a 1 an, matérialisé
- experiment_arm_lookup — créé il y a 9 mois

### 🟠 Versions matérialisées inutilisées (2)  [depuis endpoint-versions]
- monthly_active_users — v3 matérialisée, last_executed_at null (actuellement sur v4 — dématérialiser v3)
- order_summary — v1 matérialisée, last_executed_at null

### 🟡 Obsolètes (3)
- holiday_promo_2024 — dernier appel il y a 4 mois
- ab_test_phase_1 — dernier appel il y a 2 mois
- daily_revenue_cohort — dernier appel il y a 45 jours

Ordre recommandé :
1. Investiguer la matérialisation défaillante (bloque les données fraîches)
2. Dématérialiser les versions inutilisées (libère stockage + compute)
3. Désactiver les endpoints jamais appelés (si l'utilisateur confirme)
4. Examiner les endpoints obsolètes avec l'utilisateur

Le format exact importe moins que : priorisé, groupé, actionnable, et transmission claire.

5. Proposer l'étape suivante

Terminez par une question claire, pas une décision :

• « Veux-tu que je dématérialise les versions inutilisées ? » — nécessite endpoint-update avec is_materialized: false par version
• « Veux-tu que je désactive les endpoints jamais appelés ? » — nécessite endpoint-update avec is_active: false
• « Veux-tu que je creuse la matérialisation défaillante ? » — transmet à diagnosing-endpoint-performance

N'agissez jamais à partir de l'audit seul. Désactiver ou dématérialiser affecte les consommateurs API externes ; confirmez toujours avant de modifier.

Exemple d'interaction

Utilisateur : « Audit mes endpoints »

Étapes de l'agent :
- execute-sql sur system.data_modeling_endpoints → 12 endpoints (4 matérialisés)
- execute-sql sur query_log groupés par name → 8 endpoints ont des appels
- endpoint-materialization-status sur chaque endpoint matérialisé → 1 défaillant
- endpoint-versions sur les matérialisés → order_summary v2's last_executed_at est null

- Rapport :
  « Trouvé 6 choses à regarder parmi 12 endpoints :

   🔴 Matérialisations défaillantes (1)
   - monthly_active_users (v2) — matérialisation défaillante hier avec
     'memory limit exceeded'. L'endpoint reste appelable en ligne mais
     les réponses seront plus lentes.

   🟠 Jamais appelé via clé API (3)
   - legacy_funnel_v1 — créé il y a 11 mois
   - test_export — créé il y a 3 mois
   - admin_dump — créé il y a 8 mois, matérialisé (gaspillage)

   🟠 Versions matérialisées inutilisées (1)  [depuis endpoint-versions]
   - order_summary v2 — matérialisée mais son last_executed_at est null
     tandis que v3 est courant. Probablement sûr de dématérialiser v2.

   🟡 Obsolètes (1)
   - holiday_2024 — dernier appel il y a 5 mois

   Avertissement : l'utilisation compte uniquement les appels en clé API personnelle ;
   les exécutions depuis le playground et le dashboard ne sont pas comptées. La récence
   par version vient de endpoint-versions et est clairsemée. Confirmez avant de désactiver.

   Veux-tu que je commence par la matérialisation défaillante, ou nettoie la
   version inutilisée d'abord ? »

Notes importantes

• L'audit est en lecture seule. N'appelez jamais d'outils destructeurs depuis ce flux. Transmettez ou confirmez avant toute modification.
• Vide = sain. Ne remplissez pas un rapport vide avec des problèmes théoriques. « Rien à nettoyer » est une bonne réponse.
• Lisez avec SQL, creusez avec l'outil de version. system.data_modeling_endpoints (métadonnées) et query_log (compteurs d'appels au niveau endpoint, récence, coût) via execute-sql répondent à la plupart de l'audit. La récence par version provient de endpoint-versions (le last_executed_at de chaque version).
• Portée clé API uniquement. L'utilisation compte uniquement les appels en clé API personnelle. Un endpoint exercé uniquement depuis l'onglet Playground ou l'app ressemblera à inutilisé. Confirmez toujours avant d'agir.
• La matérialisation coûte stockage et compute. Quand un endpoint n'a plus besoin de matérialisation, la solution la moins chère est endpoint-update avec is_materialized: false — pas supprimer l'endpoint.
• Inactif ≠ obsolète. Un endpoint avec is_active: false a été délibérément éteint. Ne recommandez pas la suppression à moins que l'utilisateur confirme qu'il est vraiment abandonné.