Exploration des logs d'exécution d'endpoint

Chaque exécution d'endpoint émet une entrée de log dans le store log_entries de PostHog. Cette skill lit ces entrées pour un endpoint spécifique pour répondre à la question « qu'est-ce qui s'est passé lors de son exécution ? ». C'est l'équivalent au niveau des logs de diagnosing-endpoint-performance (qui raisonne sur la stratégie de cache/matérialisation à partir de la config et de query_log).

Quand utiliser cette skill

« Pourquoi mon endpoint échoue / génère une erreur ? »
« Montre-moi les logs / exécutions récentes pour l'endpoint X »
« La dernière exécution a-t-elle touché le cache ? Combien de lignes a-t-elle retourné ? »
« Qu'est-ce qui s'est passé la dernière fois que l'endpoint Y a été exécuté ? »

Si la question est « cet endpoint est lent, que dois-je changer ? », utilise diagnosing-endpoint-performance. Si c'est au niveau du projet (« qu'est-ce que je peux nettoyer ? »), utilise auditing-endpoints.

À quoi ressemble une entrée de log d'exécution

Chaque exécution produit exactement une entrée. Le niveau est INFO en cas de succès et ERROR en cas d'échec, et le message porte les données supplémentaires sous forme de tokens clé=valeur consultables :

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

Signification des tokens :

Token	Valeurs	Signification
`path`	`materialized` / `inline` / `ducklake` / `ducklake_fallback`	Quel chemin d'exécution s'est déroulé
`cache`	`hit` / `miss`	Si le cache des résultats de requête a été utilisé (omis pour ducklake)
`duration_ms`	entier	Temps d'exécution écoulé
`rows`	entier	Nombre de lignes de résultats retournées
`version`	entier	Quelle version d'endpoint s'est exécutée
`error`	ex. `ResolutionError`, `HogVMException`	Classe d'erreur / nom du code HogQL (échecs uniquement)

Chaque exécution reçoit un instance_id distinct, les logs se groupent donc un par exécution dans la visionneuse.

Outils disponibles

Outil	Objectif
`endpoint-logs`	Principal. Entrées de log d'exécution pour un endpoint par nom. Filtrer par niveau, rechercher, plage de temps, instance_id ; `limit` jusqu'à 500.
`endpoint-get`	Config d'endpoint pour le contexte (version actuelle, matérialisation, type de requête)
`execute-sql`	Fallback / agrégation directe contre `log_entries` (`log_source='endpoints'`)

Filtrage

endpoint-logs expose les filtres de log standard :

level — séparés par des virgules, ex. ERROR pour voir uniquement les exécutions échouées, ou INFO,ERROR pour toutes.
search — recherche de sous-chaîne insensible à la casse sur le message. Puisque les données supplémentaires sont dans les tokens clé=valeur, tu peux rechercher cache=miss, path=inline, error=ResolutionError, ou une version=3 spécifique.
after / before — timestamps ISO pour borner la plage temporelle.
instance_id — épingler une seule exécution.
limit — 1–500 (défaut 50).

Workflow

Identifier l'endpoint par son nom. Si une URL est donnée, l'extraire de /api/projects/{team_id}/endpoints/{name}/run.
Commencer large : endpoint-logs pour l'endpoint avec une plage temporelle récente. Balayer les niveaux et tokens.
Affiner le symptôme :
- Échecs → level=ERROR ; lire le token error= et path= pour voir où ça a cassé.
- Préoccupations de cache → search=cache=miss pour voir à quelle fréquence les exécutions ratent le cache.
- Mauvais résultats → comparer rows= à travers les exécutions, et version= pour déceler une régression après un changement de version.
Pour des comptes/tendances sur de nombreuses exécutions (ex. taux d'erreur sur une semaine), passer à execute-sql contre log_entries :
```
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
```
Récupérer l'UUID de l'endpoint via endpoint-get (le log_source_id est l'id d'endpoint, pas son nom).
Résumer : ce qui échoue, depuis quand, sur quelle version/chemin, et si c'est un problème de config (transfert à diagnosing-endpoint-performance) ou un bug de requête.

Exemple d'interaction

Utilisateur : « weekly_signups a commencé à générer des erreurs ce matin »

Étapes de l'agent :
- endpoint-logs weekly_signups, level=ERROR, after=<ce matin>
  → plusieurs « Endpoint execution failed · path=inline error=ResolutionError version=5 »
- endpoint-get weekly_signups → version actuelle est v5 (mise à jour aujourd'hui)
- endpoint-logs weekly_signups, level=INFO, before=<ce matin>
  → exécutions antérieures : « path=inline cache=hit ... version=4 » réussies

- « v5 (créée ce matin) échoue avec une ResolutionError sur le chemin inline — elle ne peut pas
   résoudre une référence de table ou de champ. v4 fonctionnait bien. Cela ressemble à une mauvaise requête dans la nouvelle
   version. Veux-tu que je récupère la requête v5 (endpoint-versions) pour pouvoir la corriger, ou revenir à v4 ? »

Notes importantes

Une entrée par exécution. Ne pas s'attendre à des traces étape par étape — les endpoints logent une seule ligne de fin. Le détail vit dans les tokens, pas dans plusieurs lignes.
log_source_id est l'UUID d'endpoint, pas le nom. Pour execute-sql, le récupérer via endpoint-get en premier.
Les logs sont conservés ~90 jours (le TTL de log_entries). Les exécutions antérieures n'apparaîtront pas.
Les logs d'exécution ≠ performance de requête. endpoint-logs te dit ce qui s'est passé et pourquoi une exécution a échoué ; pour « devrais-je matérialiser / augmenter le TTL du cache ? » utilise diagnosing-endpoint-performance, qui raisonne sur la config et les métriques de coût de query_log.
Émission au mieux. Une ligne de log est émise après chaque exécution mais ne la bloque jamais — si une exécution a réussi pour l'appelant mais aucun log n'apparaît, l'émission a été abandonnée, pas la requête.

exploring-endpoint-execution-logs